What do you think?
Rate this book
API Design Patterns
"A concept-rich book on API design patterns. Deeply engrossing and fun to read." - Satej Sahu, Honeywell API Design Patterns lays out a set of design principles for building internal and public-facing APIs. In API Design Patterns you will Guiding principles for API patterns Fundamentals of resource layout and naming Handling data types for any programming language Standard methods that ensure predictability Field masks for targeted partial updates Authentication and validation methods for secure APIs Collective operations for moving, managing, and deleting data Advanced patterns for special interactions and data transformations API Design Patterns reveals best practices for building stable, user-friendly APIs. These design patterns can be applied to solve common API problems and flexibly altered to fit specific needs. Hands-on examples and relevant cases illustrate patterns for API fundamentals, advanced functionalities, and uncommon scenarios. Foreword by Jon Skeet. Purchase of the print book includes a free eBook in PDF, Kindle, and ePub formats from Manning Publications. About the technology APIs are contracts that define how applications, services, and components communicate. API design patterns provide a shared set of best practices, specifications and standards that ensure APIs are reliable and simple for other developers. This book collects and explains the most important patterns from both the API design community and the experts at Google. About the book API Design Patterns lays out a set of principles for building internal and public-facing APIs. Google API expert JJ Geewax presents patterns that ensure your APIs are consistent, scalable, and flexible. You’ll improve the design of the most common APIs, plus discover techniques for tricky edge cases. Precise illustrations, relevant examples, and detailed scenarios make every pattern clear and easy to understand. What's inside Guiding principles for API patterns Fundamentals of resource layout and naming Advanced patterns for special interactions and data transformations A detailed case-study on building an API and adding features About the reader For developers building web and internal APIs in any language. About the author JJ Geewax is a software engineer at Google, focusing on Google Cloud Platform, API design, and real-time payment systems. He is also the author of Manning’s Google Cloud Platform in Action. Table of Contents PART 1 INTRODUCTION 1 Introduction to APIs 2 Introduction to API design patterns PART 2 DESIGN PRINCIPLES 3 Naming 4 Resource scope and hierarchy 5 Data types and defaults PART 3 FUNDAMENTALS 6 Resource identification 7 Standard methods 8 Partial updates and retrievals 9 Custom methods 10 Long-running operations 11 Rerunnable jobs PART 4 RESOURCE RELATIONSHIPS 12 Singleton sub-resources 13 Cross references 14 Association resources 15 Add and remove custom methods
479 pages, Kindle Edition
Published August 17, 2021
104 people are currently reading
389 people want to read
Ratings & Reviews
Friends & Following
Create a free account to discover what your friends think of this book!
Community Reviews
Displaying 1 - 18 of 18 reviews
April 30, 2025
TLDR: This book discusses the topics when you need to design a huge and complicated SOA system. It is one of the few guidebooks providing insights of a variety of practical issues you probably have to face when you are working as a backend engineer.
This book explains the ways to design APIs with pros and cons. There are quite a fruitful topics like idempotence, long running calls, batch vs single resource oriented endpoint. I am quite impressed by the author suggesting how to differentiate the resource identification using URL with custom actions and the ways to manage those APIs with nested resource.
The book might not give readers all the answers. However, the author can at least arise questions you might not really think of. I would recommend this book to two kinds of people - (1) for those who want to learn the complexity of API design and (2) who needs to implement and draft a API framework for systems.
This book explains the ways to design APIs with pros and cons. There are quite a fruitful topics like idempotence, long running calls, batch vs single resource oriented endpoint. I am quite impressed by the author suggesting how to differentiate the resource identification using URL with custom actions and the ways to manage those APIs with nested resource.
The book might not give readers all the answers. However, the author can at least arise questions you might not really think of. I would recommend this book to two kinds of people - (1) for those who want to learn the complexity of API design and (2) who needs to implement and draft a API framework for systems.
June 24, 2022
This was good book where the author has taken pain to identify generic patterns while designing APIs. Most other books talk in a very dispersed fashion but API Design PatternsJJG piece them apart well and together in one logical grouping. He went with TypeScript for the definitions and might deter a few but that's unwarranted. One complaint though it feels repetitive and drags a lot. Overall, a good book!
July 2, 2025
- [1] broadly, we should make APIs as simple as possible for the users requirements. not necessarily less endpoints to call but more straightforward
- [2] “make the common case awesome, and the advanced case possible”. this means the common case should be the most obvious way to use your API, advanced cases should be sufficiently hidden from a typical user only interested in the common case
- [3] good apis are easy to learn and predictable
- [4] names should be expressive (explain themselves fully), simple (the minimal length to do so), and consistent (the same name is always used to refer to the same thing)
- [5] always use american english since it’s the most commonly used language in global code, for plurals e.g persons or people, check the standard accepted pluralisation in american english, in this case people
- [6] avoid prepositions like “with”, “to”, “for”. they are usually a smell because it limits future scope, e.g. ‘books_with_authors’ means we will have to add a ‘books_with_publishers’ and maybe even a ‘books_with_authors_and_publishers’
- [7] use the single form for resources (i.e. book not books)
- [8] variable name conventions (snake case/camel case/kebab case) aren’t so important as long as they are consistent
- [9] avoid deep hierarchies (and inheritance), move to referential structures
- [10] always use positive boolean values
- [11] represent large or floating point numbers in strings, utf8 normalisation form C (to avoid equality errors with different byte representations of the same unicode strings)
- [12] instead of enums to represent data, strings are preferred. this way if a new value is added the client code will see a descriptive name in an error rather than a number. an example of this is mime types
- [13] list values should be a single homogenous primitive data type, usually strings
- [14] UUIDs for resource identifiers. you can have front facing shorter versions with base64 or however that worked with the hyphens if they might need to be read on a support call
- [15] never have indexes in web apis to interact with resources in a list. web apis should always be idempotent
- [16] REST
- [17] if we ever use custom methods, we use a POST request.
- [18] custom methods should also avoid prepositions e.g. ‘POST /launchRocket’ over ‘POST /launchRocketToMars’
- [19] resources can be made for promises and schedulable jobs
- [20] associated resources should be referenced with a string ending in id e.g. “author_id”
- [21] for polymorphic resources (text message, image message) we use a polymorphic (in this case message) interface and a type field that accepts a string (not an enum)
- [22] dry run option for results on batch actions, counts, result subset
- [23] for anonymous aggregate data we use a custom write method for “entries” (rather than resources because we can’t perform methods on specific entries - we can’t get them back)
- [24] pagination for large data, page token and max page size. don’t use offset/limit params since that leaks implementation details and the underlying data representation might change, while the API will still have to support those same operations
- [25] filters should be strings with a certain syntax (like SQL) not functions, this way they are more readable and can change in the future without the baseline API changing, i.e extended with prefix matching without causing a change in the API
- [26] for versioning, start on v1, then collect breaking changes — once you have enough, make a v2. continue this and if you see that an API version has very few to no users anymore, deprecate it. alternatively, semver (major.minor.patch)
- [27] soft deletion with a delete flag or something like that with a custom undelete (expunge) method. also expire time e.g deleted automatically after 30 days, reset after undeleting (expunging)
- [28] resource revisions accessed with @ (like GitHub issues), don’t soft delete revisions
- [2] “make the common case awesome, and the advanced case possible”. this means the common case should be the most obvious way to use your API, advanced cases should be sufficiently hidden from a typical user only interested in the common case
- [3] good apis are easy to learn and predictable
- [4] names should be expressive (explain themselves fully), simple (the minimal length to do so), and consistent (the same name is always used to refer to the same thing)
- [5] always use american english since it’s the most commonly used language in global code, for plurals e.g persons or people, check the standard accepted pluralisation in american english, in this case people
- [6] avoid prepositions like “with”, “to”, “for”. they are usually a smell because it limits future scope, e.g. ‘books_with_authors’ means we will have to add a ‘books_with_publishers’ and maybe even a ‘books_with_authors_and_publishers’
- [7] use the single form for resources (i.e. book not books)
- [8] variable name conventions (snake case/camel case/kebab case) aren’t so important as long as they are consistent
- [9] avoid deep hierarchies (and inheritance), move to referential structures
- [10] always use positive boolean values
- [11] represent large or floating point numbers in strings, utf8 normalisation form C (to avoid equality errors with different byte representations of the same unicode strings)
- [12] instead of enums to represent data, strings are preferred. this way if a new value is added the client code will see a descriptive name in an error rather than a number. an example of this is mime types
- [13] list values should be a single homogenous primitive data type, usually strings
- [14] UUIDs for resource identifiers. you can have front facing shorter versions with base64 or however that worked with the hyphens if they might need to be read on a support call
- [15] never have indexes in web apis to interact with resources in a list. web apis should always be idempotent
- [16] REST
- [17] if we ever use custom methods, we use a POST request.
- [18] custom methods should also avoid prepositions e.g. ‘POST /launchRocket’ over ‘POST /launchRocketToMars’
- [19] resources can be made for promises and schedulable jobs
- [20] associated resources should be referenced with a string ending in id e.g. “author_id”
- [21] for polymorphic resources (text message, image message) we use a polymorphic (in this case message) interface and a type field that accepts a string (not an enum)
- [22] dry run option for results on batch actions, counts, result subset
- [23] for anonymous aggregate data we use a custom write method for “entries” (rather than resources because we can’t perform methods on specific entries - we can’t get them back)
- [24] pagination for large data, page token and max page size. don’t use offset/limit params since that leaks implementation details and the underlying data representation might change, while the API will still have to support those same operations
- [25] filters should be strings with a certain syntax (like SQL) not functions, this way they are more readable and can change in the future without the baseline API changing, i.e extended with prefix matching without causing a change in the API
- [26] for versioning, start on v1, then collect breaking changes — once you have enough, make a v2. continue this and if you see that an API version has very few to no users anymore, deprecate it. alternatively, semver (major.minor.patch)
- [27] soft deletion with a delete flag or something like that with a custom undelete (expunge) method. also expire time e.g deleted automatically after 30 days, reset after undeleting (expunging)
- [28] resource revisions accessed with @ (like GitHub issues), don’t soft delete revisions
October 14, 2024
I’ve spent the majority of this year writing and designing APIs. There were many design choices that had to be made in this process, which seemed fine in the short term but ended up being problematic in the long term. The book highlights why writing APIs is different from writing any other code because updating APIs continuously is not easy, as they are publicly exposed. Hence, all the initial design choices need to be thought through much more carefully than with your usual code. This book goes into great detail about many of these choices, discussing everything from how to name the endpoints of your API to how to handle asynchronous jobs. My favorite parts of the book were the discussions on Long Running Objects, Pagination, validateOnly requests, and Soft Deletion. I think most backend engineers will benefit from reading the book because its aim is to standardize API design so that users find them reliable and predictable. That being said, the book might seem like overkill since it's around 500 pages long, and it may be better suited as a handbook during the API design process to reference particular design choices.
September 19, 2022
The first four parts of the book were good and deserve five stars.
In the last two parts, the author raised a lot of topics and explained some complex API-related patterns. However, I had a feeling that we just scratched the tip of the iceberg. On the other hand, a deeper dive into these topics could have made this book 2 times longer (it already has 500 pages).
All in all, the book is great, and it is a must-read for someone who plans to design a web API.
In the last two parts, the author raised a lot of topics and explained some complex API-related patterns. However, I had a feeling that we just scratched the tip of the iceberg. On the other hand, a deeper dive into these topics could have made this book 2 times longer (it already has 500 pages).
All in all, the book is great, and it is a must-read for someone who plans to design a web API.
December 17, 2022
If your product is an API (SAAS), you need to read this book. It brings a lot of patterns about how to write Web APIs that yours customers will love. The only downside of the book is that the author goes until the definition of the API, not stepping into the implementation part. My favorite parts: definition of unique identifiers for resources, long running operations and pagination. They are all very common cases on web APIs a few developers know how to deal with it correctly.
March 20, 2025
A particularly thorough discussion of best practices for API design. The book focuses specifically on the interface, diving into implementation details only when absolutely necessary. However, that said, the book does cover many behaviors that are relevant to both interface and implementation. A good book to read after becoming familiar with an API as a user or after following a couple of API tutorials.
March 20, 2025
Overall, it’s an okay book. The author tends to drag on, and the text lacks coherence at times. I often had to reread paragraphs 2–3 times to grasp the meaning and navigate the logical jumps. The book also feels somewhat opinionated. While it discusses web APIs, the patterns seem more suited for middleware or consumer APIs rather than frontend applications. It’s a decent read if you have the time, but I found it a bit tiring.
July 13, 2022
The book does touch in a lot of topics related to API design but it is written too much using absolutisms. Many principles that are written about lack a good description of the context to which it applies. That gets quite annoying the further you read the book.
October 20, 2021
Not much substance.
April 12, 2022
A very dry and often opinionated, but nicely structured reference.
August 23, 2022
Es un must para cualquiera que quiera diseñar APIs o que trabaje con ellas
April 2, 2023
Opinionated, digestible, and applicable.
November 3, 2023
Very condensed, dry and boring. I have stopped reading at chapter 6, where it talks about IDs...like 10 pages talking about crap about IDs, just go to the point.
July 1, 2024
Read most of the chapters. The book is a nice journey into understanding different API designs, and I would recommend it as a good general reference for basic API implementation patterns.
October 29, 2024
Started off as informative and appropriately detailed but feels like the author drags on and on.
Could be used as a reference book rather than an enjoyable way to learn about api best practices.
Could be used as a reference book rather than an enjoyable way to learn about api best practices.
Read
January 21, 2026Google API design philosophy
November 4, 2023
I think that the book does overall a very good job at explaining patterns in an incremental way and with good examples.
One thing that I didn't appreciate is the fact that some chapters are too verbose. I'm not a fan of short explanations, but here I had the impression that some concepts were repeated too many times, just by using different expressions.
And in relation to my point above, I think that there are sections where the explanation starts going sideways, finally resulting in inaccurate descriptions or examples.
Overall it was a good read and I definitely learned a few things from the book.
One thing that I didn't appreciate is the fact that some chapters are too verbose. I'm not a fan of short explanations, but here I had the impression that some concepts were repeated too many times, just by using different expressions.
And in relation to my point above, I think that there are sections where the explanation starts going sideways, finally resulting in inaccurate descriptions or examples.
Overall it was a good read and I definitely learned a few things from the book.
Displaying 1 - 18 of 18 reviews