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.

7 deadly sins of API at DevoxxUK 2019

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.

Related Books

Free with a 30 day trial from Scribd

See all
  • Be the first to comment

7 deadly sins of API at DevoxxUK 2019

  1. 1. 1THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk DEADLY SINS OF {API} DESIGN THE
  2. 2. 2THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk LUIS WEIR Director Software Development Oracle Hospitality luis.weir@oracle.com uk.linkedin.com/in/lweir @luisw19 http://www.soa4u.co.uk tinyurl.com/eapim19 July 2019 apiplatform.cloud/ May 2018 ABOUT ME @luisw19
  3. 3. 3THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk This is an opinionated presentation expressing my own views.
  4. 4. 4THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk APIs are doors to information and functionality.
  5. 5. 5THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk But if you get the design and implementation wrong… https://www.boredpanda.com/funny-architecture-construction-fails/?utm_source=google&utm_medium=organic&utm_campaign=organic
  6. 6. 6THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk So avoid common API-design pitfalls by not committing any of the 7 Deadly Sins 1- LUST 2- GLUTTONY 3- GREED 4- SLOTH 5- WRATH 6- ENVY 7- PRIDE
  7. 7. 7THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk So avoid common API-design pitfalls by not committing git commit(ing) any of these sins 1- LUST 2- GLUTTONY 3- GREED 4- SLOTH 5- WRATH 6- ENVY 7- PRIDE
  8. 8. 8THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk THE 7 DEADLY SINS 1- LUST Unrestrained desire for something Try this tool
  9. 9. 9THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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?
  10. 10. 10THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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 & Contract 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 inspector OpenAPI-to-Postman
  11. 11. 11THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk THE 7 DEADLY SINS 2- GLUTTONY The over- indulge specially by over eating
  12. 12. 12THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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
  13. 13. 13THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 2- GLUTTONY: Deliver us from evil Remove unnecessary layers by: 1. Seriously questioning what is the 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 discovery discovery
  14. 14. 14THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk THE 7 DEADLY SINS 3- GREED Intense and selfish desire for something Derek Michael Brennan
  15. 15. 15THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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: • HATEOAS to the extreme… • Extremely granular resource designs • Batch downloads via paginated payloads APIGateway ++ bandwidth = $$ & << UX
  16. 16. 16THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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
  17. 17. 17THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk THE 7 DEADLY SINS 4- SLOTH Laziness, lack of effort
  18. 18. 18THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 4- SLOTH: REST In Peace (RIPfull) Ignoring REST architectural principles. E.g.: • Operations in URIs: [GET] https://eg.com/getAllorders [GET] https://eg.com/getOrder?id=xxx [POST] https://eg.com/newOrder [PUT|DELETE] https://eg.com/updateOrder?id=xxx • Unbounded responses? [GET] https://eg.com/orders so, send back 1m orders? • Use of both singulars and plurals in a single API [GET] https://eg.com/orders [GET] https://eg.com/order/1234 • Ignoring HTTP status codes [POST] https://eg.com/orders {…} Response: HTTP 200 Ok  Really?
  19. 19. 19THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 4- SLOTH: REST In Peace (RIPfull)..continues • Go figure out how to find a related resource [GET] https://eg.com/orders [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…
  20. 20. 20THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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 (but not to the extream). Check Richardson’s maturity model • Idempotency on methods: [GET|PUT|PATCH|DELETE]
  21. 21. 21THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk THE 7 DEADLY SINS 5- WRATH Uncontrolled feelings of hatred and anger
  22. 22. 22THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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 API Doc Angry developer Is this supposed to be an API Doc?
  23. 23. 23THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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. doc.myapi.com) 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
  24. 24. 24THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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) https://ordersms.docs.apiary.io/#
  25. 25. 25THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 5- WRATH: Recommend Good examples of API docs: • Stripe API: https://stripe.com/docs/api • Strava API: https://developers.strava.com/docs/reference/ Some good tools: • Apiary.io: supports OAS, API Blueprint, rich documentation, Mocking server, spec testing with Dredd, • Snowboard & Aglio: really nice API blueprint parsers/renderers.
  26. 26. 26THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk THE 7 DEADLY SINS 6- ENVY Jealousy towards another's happiness
  27. 27. 27THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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? https://imgur.com/a/J3ttg {REST}
  28. 28. 28THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk Let’s put it into perspective https://trends.google.com/trends/explore?date=2004-01-10%202019-05-09&q=GraphQL,REST%20API,OData,WSDL trend WSDLGraphQL REST API OData Feb 2004 May 2019
  29. 29. 29THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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" } ] } }
  30. 30. 30THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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] https://restcountries.eu/rest/v2/{resource} {JSON} REST COUNTRIES [HTTP/POST] https://www.google.co.uk/search?q={search} {JSON} • Devoxx London: GraphQL as an alternative approach to REST, • 4 part code samples: https://github.com/luisw19/graphql-samples
  31. 31. 31THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk THE 7 DEADLY SINS 7- PRIDE Inflated sense of one's accomplishments
  32. 32. 32THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 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! http://www.constructionhunter.com.au/blog/industry-news/20- photos-that-will-make-you-question-your-faith-in-humanity
  33. 33. 33THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk 7- PRIDE: Deliver us from evil No better accomplishment as an API designer/developer to create an API that is fit for purpose and actually used. Avoid the picture on the right Design your API first with usability in mind. https://www.pinterest.co.uk/pin/504543964485602355 https://www.boredpanda.com/funny-architecture-construction- fails/?utm_source=google&utm_medium=organic&utm_campaign=organic
  34. 34. 34THE 7 DEADLY SINS OF {API} DESIGN @LUISW19#DevoxxUk Questions? A similar presentation is available at www.soa4u.co.uk : www.soa4u.co.uk/2018/10/the-se7en-deadly-sins-of-api-design.html

    Be the first to comment

    Login to see the comments

  • tpillai

    May. 14, 2019
  • powerirs

    Jan. 1, 2020

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.

Views

Total views

3,252

On Slideshare

0

From embeds

0

Number of embeds

2,111

Actions

Downloads

14

Shares

0

Comments

0

Likes

2

×