The Se7en Deadly Sins of API Design

During Oracle Code One 2018 (formerly Java One) I was lucky enough to deliver for the first time a funny yet insightful presentation titled "The Seven Deadly Sins of API Design" focused on API design anti-patterns and how to overcome them. I was also fortunate to have presented a similar session at Sangam 2018 in Bangalore and most recently at Devoxx UK 2019 in London.

This presentation was partly inspired by Daniel Bryant the 7 Deadly Sins of Microservices however with full focused on the topic of API design and API-led architectures, not so much on Microservices (though the too are so closely related that not talking about Microservices in some areas is impossible). But my main motivation was really around the fact that we're all sinners when it comes to making mistakes. When I first started designing REST APIs (or before that SOAP/WSDL based services), I myself made so many mistakes. However the main thing is to learn from them. And not just from our own mistakes, but that of others. So my presentation is about this, shortlisting the seven most common pitfalls on API design and architectures and then using the deadly sins as a vehicle to tell a story on how to "deliver us from evil".

The 7 deadly sins, also known as capital sins, represent corrupt and/or perverse versions of love. In this case, corrupt or perverse APIs.

Following a description of each deadly sin including a description of what anti-pattern I went for on each:
  1. Lust: unrestrained desire for something. In this sin I talk about why sometimes we focus so much in the implementation aspects of an API, but specially on what tools to us, and not so much on the usability of the API itself which also means getting feedback from the audience of the API to ensure the interface is fit for purpose and intuitive enough -something I refer to as API-design first.
  2. Gluttony: the over-indulge specially by over eating. I use this sin to articulate the fact that many API implementations end-up with several layers of middleware (e.g. mainly load balancers and multiple API Gateways) before an actual service endpoint is actually reached. This is bad for many reasons (e.g. added complexity, additional costs, etc) and my conclusion is that we should not just add layers on top of layers for no strong reason. In some scenarios it might be inevitable but as rule of thumb we should question any additional layer added on top of the service. For example, I think one API Gateway should be enough and is justified, adding another one? umnn... 
  3. Greed: intense and selfish desire for something. In here I talk about how many times a frontend results in poor user experience consequence of chatty APIs that require several API calls in order to construct e.g. a single UI page. Instead, I talk about how to prevent this sin by implementing different patterns such as web-hooks and/or API composition (e.g. with GraphQL).
  4. Sloth: laziness, lack of effort. an obvious one in my view, I highlight the fact that even though REST as an architectural style is well documented on the web and stablished industry wide still we go about implementing "corrupt and perverse" versions of REST. I then describe some REST (obvious?) best-practices, though in my view, there is no excuse for a poor RESTful design because of the aforementioned.
  5. Wrath: uncontrolled feelings of hatred and anger. In this sin I use as example the fact that many APIs are poorly documented or not documented at all which can results in angry developers. To present this sin, I talk about some documentation best-practices and show a diagram depicting what a good API documentation should look like.
  6. Envy: jealousy towards another's happiness. My favourite one (and I think the audience's too), I talk about the fact that some times we get hung-up on a specific architectural style without considering alternatives that might better suited for the problem at hand.  Look at the slides, you'll laugh.
  7. Pride: Inflated sense of one's accomplishments. And lastly I talk about bottom-up API design, which I refer to as the result of auto-generating API specs either from code or from a database relational models without first designing/mocking the interface and establishing feedback-loops. I am not in favour of this approach for many reasons but most notably because of the lack of abstraction and separation of concerns. For example, If an API is derived from a relational model and an API consumer binds to the interface, then a change in the database might end-up propagating all the way to the user interface. BAD IDEA. But this also means, as in the case of Lust, usability and feedback loops are not really considered as there is no API design, instead a database or backend system design is forced upon API consumers.

Here's the video recording from the DevoxxUK presentation:


And here's the deck as presented.


As you can probably tell, the theme of the presentation is inspired by the movie Se7en. If you haven't seen it! please do as it's brilliant.

I am also glad to say that the session was very well attended (standing room) both at Code One and Devoxx, which is always rewarding given the amount of it takes to prepare a session.

Code One 2018 Audience (San Francisco)

Devoxx UK 2019

Last but not least I want to thank my current team at Oracle (specially Boro Petrovic) for allowing me to come and share my knowledge in this event and also my former team in Capgemini, Phil, Sander, Yury, Ben, Amy, James for giving me feedback as it helped a lot in maturing the story line.

Comments

Post a Comment