Disclaimer: This post includes affiliate links; I may receive compensation if you purchase the book from the different links provided in this post. This review is about by JJ Geewax from Manning. API Design Patterns I how I'm trying to get to speed in the API world: reading books, viewing relevant YouTube videos, and reading relevant Internet Engineering Task Force Request For Comments. already mentioned Facts 30 chapters, $35.00 The author is a Principal Software Engineer at Google He's also the author behind https://google.aip.dev/ Chapters Introduction Design principles
3. Naming
4. Resource scope and hierarchy
5. Data types and defaults Fundamentals
6. Resource identification: How to identify resources in an API
7. Standard methods: The set of standard methods for use in resource-oriented APIs
8. Partial updates and retrievals: How to interact with portions of resources
9. Custom methods: Using custom (non-standard) methods in resource-oriented APIs
10. Long-running operations: How to handle methods that are not instantaneous
11. Rerunnable jobs: Running repeated custom functionality in an API Resource relationships
12. Singleton sub-resources: Isolating portions of resource data
13. Cross references: How to reference other resources in an API
14. Association resources: How to manage many-to-many relationships with metadata
15. Add and remove custom methods: How to manage many-to-many relationships metadata
16. Polymorphism: Designing resources with dynamically-typed attributes without Collective operations
17. Copy and move: Duplicating and relocating resources in an API
18. Batch operations: Extending methods to apply to groups of resources atomically
19. Criteria-based deletion: Deleting multiple resources based on a set of filter criteria
20. Anonymous writes: Ingesting unaddressable data into an API
21. Pagination: Consuming large amounts of data in bite-sized chunks
22. Filtering: Limiting result sets according to a user-specified filter
23. Importing and exporting: Moving data into or out of an API by interacting directly with a storage system Safety and security
24. Versioning and compatibility: Defining compatibility and strategies for versioning APIs
25. Soft deletion: Moving resources to the "API recycle bin"
26. Request deduplication: Preventing duplicate work due to network interruptions in APIs
27. Request validation: Allowing API methods to be called in "safe mode"
28. Resource revisions: Tracking resource change history
29. Request retrial: Algorithms for safely retrying API requests
30. Request authentication: Verifying that requests are authentic and untampered with Each chapter follows the same structure: design pattern Motivation: what problem solves the pattern Overview: a short description of the pattern Implementation: an in-depth explanation of the pattern. It's structured into different subsections. Trade-offs: patterns have strong and weak points; this section describes the latter Exercises: a list of questions to verify that one has understood the pattern Pros and Cons Let's start with the good sides: As I mentioned above, the structure of each chapter dedicated to a design pattern is repetitive. It makes the chapter easy to consume, as you know exactly what to expect. In general, I read my technical books just before going to sleep because I'm pretty busy during the day. Most books have long chapters, requiring me to stop mid-chapter when I start to fall asleep. When you start again, you need to get back a few pages to get the context back. The length of a chapter on API Design Patterns is ideal: neither too long nor too short. The Design Principles section starts from the basics. You don't need to be an expert on API to benefit from the book. I was not; I hope that I'm more seasoned by now. I was a bit dubious at first about the Exercises section of each chapter, for it didn't provide any solution. However, I came to realize it activates the mechanism: instead of passively reading, actively recall what you learned in answering questions. It improves the memorization of what was learned. As an additional benefit, you can learn in a group, compare your answers and eventually debate them. active recall Now, I've some critics as well: Some patterns are directly taken from . It's not a problem , but when it's the case, there's no discussion about possible alternatives. For example, the chapter on custom methods describes how to handle actions that don't map precisely to an HTTP verb: a bank transfer is such an action because it changes two resources, the "from" and the "to" accounts. Google's API Improvement Proposals per se at all The proposed I is for the HTTP URI to use a character followed by the custom verb, , . That's an exciting proposal that solves the lack of mapping issue. But there are no proposed alternatives nor any motivation for why it should be this way. As an engineer, I can hardly accept implementing a solution with such far-reaching consequences without being provided with other alternatives with their pros and cons. Google AP : e.g. /accounts/123:transfer Last but not least, the book doesn't mention any relevant RFC or IETF draft. Chapter 26 describes how to manage request deduplication, the fact that one may need to send the same non-idempotent request repeatedly without being afraid of ill side effects. The proposed solution is good: the client should use a unique key, and if the server gets the same key again, it should discard the request. It's precisely what the IETF draft describes: . Still, there's no mention of this draft, giving the feeling that the book is disconnected from its ecosystem. The Idempotency-Key HTTP Header Field Author's Replies For once, I was already in touch with the author. I offered him an opportunity to review the post. Since his answers are open, I decided to publish them with his permission: Why isn't their more discussion about alternatives? I think you're right -- and I actually had quite a bit of discussion of the alternatives in the original manuscript. And I ended up chopping them out. One reason was that my editor wanted to keep chapters reasonably sized, and my internal debates and explanations of why one option was better or worse than another was adding less value than "here's the way to do it". The other reason was that I "should be opinionated". If this were a textbook for a class on exploring API design I could weigh all the sides and put together a proper debate on the pros and cons of the different options, but in most cases there turned out to be a very good option that we've tried out and seen work really well over the course of 5+ years ( , for custom methods). In other cases we actively didn't have that and the chapter a debate showing the different alternatives ( , Versioning). If I could do a 600-700 pages, I think it would have this for you. e.g. : is e.g. Why aren't their more references to IETF standards? This is a glaring oversight on my part. There are a lot of RFCs and I do mention some (e.g., RFC-6902 in Partial Updates, etc), but I haven't pulled in enough from that standards body and it's a mistake. If we do a 2nd edition, this will be at the top of the list. Conclusion Because of the couple of cons I mentioned, falls short of being a reference book. Nonetheless, it's a great book that I recommend to any developer entering the world of APIs or even one with more experience to round up their knowledge. API Design Patterns Originally published at on January 15th, 2023 A Java Geek

Follow @nicolas_frankel on Twitter

Read My Stories

Read all my posts!

Too Long; Didn't Read

Questions about cloud security? Get answers here.

A Review of API Design Patterns: The Pros and Cons

Too Long; Didn't Read

Nicolas Fränkel

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

A Review of API Design Patterns: The Pros and Cons

Too Long; Didn't Read

Nicolas Fränkel

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES