API Design Patterns
Design principles for building internal and public-facing APIs
JJ Geewax
API Design Patterns lays out a set of design principles for building internal and public-facing APIs.
The use of design patterns in software development is prevalent, primarily because they are templates to solve common problems providing repeatable solutions, which can be applied common problems. The benefit of software design patterns lies in their re-usability and extensibility of the already developed applications enabling more sophisticated and advanced approaches.
API are a set of instructions, standards or requirements that enables a software or app to employ features/services of another app, platform or device for better services.
It stands to reason, that after several years of Web API development, there must be recurring patterns and practices that can be utilised by software development teams to develop truly scalable, robust, secure and consistent web API's.
Why I read this book
it seems almost inevitable today, that whatever software project you embark on there will always be a requirement for a web based API. Indeed over the past several years I have been on many projects that have involved as much. Yet it seems, whenever the teams embark on these types of projects they think they are the first to do so. I often find teams repeating the same mistakes, and in most cases never actually successfully implement an API and rather create a loosely collated collection of functions available over HTTP, which is not the same thing.
Many of the issues I've seen occur out in the wild, can primarily be put down to poor planning and execution of the API project and in many cases I've seen that the issues have arisen by back end developers primarily developing API's to service the Front end requirements or use cases. However, many of those problems can be overcome by following approaches defined in Principles of Web API.
Principles of Web API
Delivering Value with APIs and Microservices
Principles of Web API Design brings together principles and processes to help you succeed across the entire API design lifecycle.
Other common recurring problems are that teams often just get the implementation wrong, with issues as I discussed in Why I don’t like layered architecture for microservices and How to Implement Vertical Slice Architecture. These issues typically involve teams implementing the wrong system approaches to solve problems.
What I like about this book
This book provides a comprehensive analysis of key API patterns that will improve your design skills, leading to consistent APIs that consumers crave. The author goes into great depth to explain not only why patterns are useful in API design, but why these specific patterns lead to better APIs.
The author clearly has an extensive experience designing and developing a comprehensive set of API's and is able to draw on this experience to present a foundational reference packed full of expert well-thought-out examples, with modern API design patterns.
I particularly learned more from this book, than I originally anticipated and appreciated that I had previously barely utilised the rich HTTP design patterns available via REST. Discovering that I can extend the typical REST methods with custom methods and that there was a convention one could follow to do so!
I particularly enjoyed and learned a lot from the chapters on Pagination and Partial Updates and Retrievals. Pagination enables large collections of results or large single resources to be consumed in a series of bite-sized chunks rather than as a single large API response using three special fields: maxPageSize , pageToken , and nextPageToken .
If there are more pages, a response will include a nextPageToken value, which can be provided in the pageToken field of a subsequent request to get the next page. We rely on a maximum page size rather than an exact page size as we don’t know how long it will take to fill a page exactly and must reserve the ability to return even before a page of results is fully populated.
There was also the additional bonuses of discovering patterns for handling long running operations and file based operations.
The insights from this book are what lead me to learn about JSON Patch and the prompt to share what I learned by writing the How to use JSONPatch in .net core article. If it had not been for this book, I may never have discovered this approach.
There are not many code samples and the vast majority of the ones that are , are in Java but they are clear and concise enough for developers in any language to understand.
I found authors style of writing and explanations to be clear, really informative and easy to read.
Why I recommend this book
This book is s one of the few guidebooks providing insights of a variety of practical issues you're most likely to face as a back end engineer, providing common patterns and approaches ways to design APIs with pros and cons of each.
I firmly believe you’ll improve the design of your APIs and discover techniques for tricky edge cases. Due to the fact that the book provides precise illustrations, relevant examples, and detailed scenarios make every pattern clear and easy to understand. It certainly did so for me.
This book should be required reading for any team or developers embarking, planning or even currently developing an API regardless of whether there are plans for the API to be released publicly or not. There are a number of best practice patterns and implementations you cane learn to your advantage.
API Design Patterns
API Design Patterns lays out a set of design principles for building internal and public-facing APIs, providing a collection of best practices and design standards for web and internal APIs.
- What is this Directory.Packages.props file all about? - January 25, 2024
- How to add Tailwind CSS to Blazor website - November 20, 2023
- How to deploy a Blazor site to Netlify - November 17, 2023