Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

The 7 Deadly Sins of API Design


Published on

There is no doubt that Web APIs have become a fundamental aspect of modern architectures. However how to distinct a “good” API from an “evil” one is a topic for debate and one that often ends up in a “religious” debate. However, the one thing that is clear to most people, is that it all starts with a design, and getting that design right up-front will likely result in less headaches down the line.

So how to avoid “evil” APIs?

In this presentation, I will talk about the 7 most common pitfalls I’ve come across when doing API design in large implementations. With real-life examples, I will describe why such pitfalls deserved to be called “evil” and how to remediate them with “good" design practices.

The presentation will also touch upon how API-design first techniques can be applied to solve prevent some of the common issues.

It will be a highly interactive session with good balance of theory and practice.

Published in: Technology
  • Be the first to comment

The 7 Deadly Sins of API Design

  3. 3. 3THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 LUIS WEIR CTO Capgemini UK Oracle Groundbreaker Ambassador & Ace Director @luisw19 Q2 2019 May 2018 ABOUT ME
  4. 4. 4THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 THE 7 DEADLY SINS 1- LUST Unrestrained desire for something Try this tool
  5. 5. 5THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 1- LUST: The Perfectly Useless API Focusing mainly on runtime, implementation tech, CICD (e.g. K8s, APIG, APIMGW, Mesh, Pipelines, etc) and forgetting about the API usability. The motivations: Typically: • Fashion, • CV building, • Comfort zones, • Even office politics?
  6. 6. 6THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 1- LUST: Deliver us from evil API design first, implementation second. It doesn’t take fancy tools or complex steps to do this: 1. First capture what the needs really are in a design, 2. Quickly mock API endpoints, share, get feedback, 3. Once design is complete, ensure implementation consistency by testing design against service. Design Build & Test Try 01 • API docs and mock endpoints available in the Dev Portal • API consumers try the API and give feedback 02 03 Feedback-loops
  7. 7. 7THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 THE 7 DEADLY SINS 2- GLUTTONY The over- indulge specially by over eating
  8. 8. 8THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 2- GLUTTONY: The API Sandwich Architecture Purposely adding layers on top of layers of API middleware unnecessarily adding complexity and costs without clear business benefits. ßBackend for Frontend API Consumerà ß Service The motivations: There are many but commonly: • In the name of abstraction and decoupling?? • Unawareness of, or avoidance to use, existing API infrastructure, • Solving a network problem (e.g. geo- routing) • Other sins? e.g. envy, pride?. LBà ßInternal API Gateway ßAPI Micro- Gateway LBà LBà LBà
  9. 9. 9THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 2- GLUTTONY: Deliver us from evil Remove unnecessary layers by: 1. Seriously questioning what is unique value each layer adds 2. Adopt domain-driven design principles. Get the bounded contexts right, 3. Consider a service mesh instead more layers of API Gateways (or event sourcing), 4. Checkout API Gateway Pattern. API Consuming Applications Customers Service Orders Service Logistics Service Service Registry Frontend Specific Service API Gateway Backend Frontends Service M esh discovery discovery
  10. 10. 10THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 THE 7 DEADLY SINS 3- GREED Intense and selfish desire for something
  11. 11. 11THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 3- GREED: The Chatty API Abusive use of network resources resulting in bad API consumption experience: 1. A client application has to make several API calls just to build up a single page, 2. HTTP GET as a strategy to do batch data downloads. The motivations: • Selfishness: I’ve built my APIs, it’s up to the UI how to use it • Easier to extend an existing API with e.g. pagination, HTTP chunking, etc. APIGateway ++ bandwidth = $$ & << UX
  12. 12. 12THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 3- GREED: Deliver us from evil Optimise number of API calls by adopting a different approach: 1. Webhooks as means to implement web events (push not pull –only send data changes) 2. Implement an API Composition pattern (e.g. consider GraphQL?) APIGateway EventHub APIGateway API Composition Webhooks subscribe Web events Composition Service
  13. 13. 13THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 THE 7 DEADLY SINS 4- SLOTH Laziness, lack of effort
  14. 14. 14THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 4- SLOTH: REST In Peace (RIPfull) Ignoring REST architectural principles. E.g.: • Operations in URIs: [GET] [GET] [POST] [PUT|DELETE] • Unbounded responses? [GET] àso, send back 1m orders? • Use of both singulars and plurals in a single API [GET] [GET] • Ignoring HTTP status codes [POST] {…} Response: HTTP 200 Ok à Really?
  15. 15. 15THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 4- SLOTH: REST In Peace (RIPfull)..continues • Go figure out how to find a related resource [GET] [orders{ order:{ "id":"or001", customer: { "id":"cust123" à where is it? } }, … }] The motivations: Still a mystery to me… but perhaps: • Using SOAP to REST convertors? • Lack of understanding of REST? • Or simply SLOTH…
  16. 16. 16THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 4- SLOTH: Deliver us from evil Lots of content online for best practices.. So no excuse Homer. In any case: • Use HTTP verbs Search, Create: [GET|POST] /orders?{search filters} Read, Update, Partly update, Remove: [GET|PUT|PATCH|DELETE] /orders/{id} • Plural nouns are best (see above) • Use limits/offsets to constraint response /orders?limit=50&offset=150&{additional filters} • Respect HTTP status codes e.g. 2xx – Success, 4xx – Client errors, 5xx – Server errors. à check this link • HATEOAS unless impossible. Check Richardson’s maturity model • Idempotency on methods: [GET|PUT|PATCH|DELETE]
  17. 17. 17THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 THE 7 DEADLY SINS 5- WRATH Uncontrolled feelings of hatred and anger
  18. 18. 18THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 5- WRATH: No (documented?) API What can be worse than not having an API? Well, an undocumented API or even worse, a poorly documented API… The motivations: Most likely: • An accidental API (those that weren’t meant to used but sort of did), • Time pressures (deadlines), • Other sins .. Sloth My API Doc
  19. 19. 19THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 5- WRATH: Deliver us from evil An API is only as good as its doc. The ABC of a Good API: • Absent API doc = No API, • Bad documentation = Angry Developers, • Can’t find it = re-inventing wells (duplicate APIs) A good API Doc should include API Page (e.g. Nav: Get Started Intro Authentication Errors Constraints Change Log Resource Name Nav: Resources Resource Name Search Create Read Update Delete Curl JS | Java |.. API Mock URL Sample Requests URI / Params description Sample Responses Description of resource. What is it? What does it do? GET /samples?{} Description of the endpoint. Search POST /samples Description of the endpoint. Create Resource Name
  20. 20. 20THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 5- WRATH: Deliver us from evil An API is only as good as its doc. The ABC of a Good API: • Absent API doc = No API, • Bad documentation = Angry Developers, • Can’t find it = re-inventing wells (duplicate APIs)
  21. 21. 21THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 5- WRATH: Recommend Good examples of API docs: • Stripe API: • Strava API: Some good tools: • supports OAS, API Blueprint, rich documentation, Mocking server, spec testing with Dredd, • full API design lifecycle for OAS, • RedDoc: generates responsive web apps from OAS specs. • Snowboard & Aglio: really nice API blueprint parsers/renderers.
  22. 22. 22THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 THE 7 DEADLY SINS 6- ENVY Jealousy towards another's happiness
  23. 23. 23THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 6- ENVY: The Disloyal API Designer So you’re a REST fan. Considering GraphQL as an alternative it’s just unconceivable. Even if UI developers favour it. The motivations: Multiple valid reasons: • Existing investment in REST APIs, • Current skills in the organisation, • Reluctance to change? • Other since: Pride? {REST}
  24. 24. 24THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 Let’s put it into perspective,REST%20API,OData,WSDL WSDLGraphQL REST API OData Feb 2004 Oct 2018
  25. 25. 25THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 6- ENVY: Deliver us from evil GraphQL IS NOT a silver bullet. But it has some great features: • Best for API usability (specially with GraphiQl, get only the data you want), • Best for API composition pattern, • It can perfectly co-exist with REST. REST REST REST API GraphQL Define Schema type Country { id: ID! name: String! code: String! } type query { countries: [Country] } GraphQL Service GraphQL Client Quickly write and run queries { getCountries(name:"great") { name } } GraphQL Client Get exactly what you asked for { "data": { "countries": [ { "name": "United Kingdom" } ] } }
  26. 26. 26THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 6- ENVY: Recommend Browser GraphiQL { query } GraphQL Server: Apollo/Express GraphQL Service Graphiql GraphQL Schema GraphQL Endpoint Query Operation {JSON} [HTTP/POST] {JSON} { data } [HTTP/GET]{resource} {JSON} REST COUNTRIES [HTTP/POST]{search} {JSON} • Devoxx London: GraphQL as an alternative approach to REST, • 4 part code samples:
  27. 27. 27THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 THE 7 DEADLY SINS 7- PRIDE Inflated sense of one's accomplishments
  28. 28. 28THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 7- PRIDE: Bottom-up API Design Unanimously deciding what the interface should be. No design feedback loops. The motivations: Most likely: • Easier/quicker to auto-generate endpoints from data sources, • Time pressures (deadlines), • Or just Pride!
  29. 29. 29THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 7- PRIDE: Deliver us from evil No better accomplishment as an API designer/developer to create an API that is actually used and good feedback is received. Avoid the picture on the rightà Design your API first with usability in mind.
  30. 30. 30THE 7 DEADLY SINS OF {API} DESIGN @LUISW19 This message contains information that may be privileged or confidential and is the property of the Capgemini Group. Copyright © 2018 Capgemini. All rights reserved. A global leader in consulting, technology services and digital transformation, Capgemini is at the forefront of innovation to address the entire breadth of clients’ opportunities in the evolving world of cloud, digital and platforms. Building on its strong 50-year heritage and deep industry-specific expertise, Capgemini enables organizations to realize their business ambitions through an array of services from strategy to operations. Capgemini is driven by the conviction that the business value of technology comes from and through people. It is a multicultural company of 200,000 team members in over 40 countries. The Group reported 2017 global revenues of EUR 12.8 billion. About Capgemini Learn more about us at