My team is in the earliest stages of introducing APIs as the long term replacement for an existing mature SOA environment. This will be a process that takes many years and to kickstart the process I’ve been scouring the internet for high quality training material. Most tutorials I’ve found focus on publishing whatever you’ve already built with OpenAPI documentation, and less about actually designing good APIs in the first place. These are the best resources I’ve found so far, in no particular order:
-
Domain Driven Design: Tackling Complexity in the Heart of Software by Eric Evans:
This is the DDD book to start with, it covers the why and how-to distill your business domain down into a well understood model before writing any code. It is starting to show it’s age when it comes to specific programming methodologies, but the core concepts stand the test of time.
-
Build APIs You Won’t Hate by Philip Sturgeon:
Another one that is starting to show its age when it comes to specific implementation technologies, of note Swagger was still in its infancy when this came out, but there is a lot of actionable information here. It was a very easy read, with a casual tone. I read it in about two hours cover to cover.
-
The OpenID Connect Handbook by Brian Krebs at Auth0:
While not strictly API-design related, this short book gives a detailed explanation of OAuth 2.0 and OIDC, how they are related and a common use case for each of the grant types and authorisation flows. This has been a good resource for sharing with teams who only need to consume an API using OAuth or OIDC, without needing to know the protocols inside and out.
In my research for this post I found the following books that I’ll be reading in the coming months:
- The Design of Web APIs by Arnaud Lauret
- Designing APIs with Swagger and OpenAPI by Joshua S. Ponelat and Lukas L. Rosenstock
- Practical Microservices by Ethan Garofolo
If you’ve got additional recommendations, please send them my way on Twitter @mhdotnet.