Suggestions for books about API design?

Not a book, but the best recorded talk ever given about API design is (IMO) by Joshua Bloch, in a 2007 tech talk at Google. "How to Design a Good API and Why It Matters".

He was one of the creators of the Java Collections API and the Java Executor Framework, two of the most durable and most widely-copied APIs ever. That may not seem relevant for an HTTP/REST API, but it is. The design principles are timeless. Here's that reference:

https://twitter.com/amontalenti/status/1260030567501840386?s...

When I had to design a widely-used "HTTP/RESTful" API a few years back, I wrote a summary of the design principles here. It also includes a reference to an old O'Reilly book on the topic, which I summarized:

https://www.parse.ly/help/api/restful-apis

Don Norman’s “The Design of Everyday Things” (https://en.m.wikipedia.org/wiki/The_Design_of_Everyday_Thing...). Yes, API design has its own gotchas and specific practices—but some of the best (and worst) APIs I’ve ever interacted with were good (or bad) for the same reasons any kind of design can be good ( or bad): affordances, feedback, coherent conceptual models, and so on.

Stripe blog posts are unparalleled

https://stripe.com/blog/api-versioning

https://stripe.com/blog/idempotency

It goes beyond "what is rest" and real life UX of apis

I’d highly recommend reading Roy Fielding’s dissertation paper where he introduced REST.

For anyone who hasn’t read it, it will fundamentally change how you think about REST and APIs for network services, and you’ll create much better APIs armed with that deeper understanding.

Paper: https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

Chapter introducing REST: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...

https://apisyouwonthate.com and their book(s) offer good advices.

Not a book, but MS REST API Guidelines are pretty good although they don't cover funky important details like how to properly do REST operations/actions.

https://github.com/microsoft/api-guidelines

This is short one based on RedHat VM engineer experience:

https://restful-api-design.readthedocs.io/en/latest/intro.ht...

Manning has a solid books on topic:

https://www.manning.com/books/the-design-of-web-apis

https://www.manning.com/books/api-design-patterns

I've found https://aip.dev really useful! In fact this is a canonical resource for building REST apis at Google.

I would suggest having a close look at the OpenAPI specification as a way to bound and constrain your REST API design: https://swagger.io/specification/

Once you start thinking in terms of requests, responses, parameters, schemas etc the rest should easily fall into place! You also get the benefit of having a machine readable definition of your API if you write your design with the spec.

About REST : REST API Design Rulebook by Mark Massé (O'Reilly).

My reference when I'm designing a REST API.

https://www.oreilly.com/library/view/rest-api-design/9781449...

Domain Driven Design: https://smile.amazon.com/Domain-Driven-Design-Tackling-Compl...

It's not about designing APIs, it's about designing your software to reflect the reality you're encoding into your software. It's a book of first principles that you can apply to any software you design.

Not a book, but the current issue of https://increment.com/ is about APIs.

A philosophy of software design - John Ousterhout

This has an interesting generic discussion of API design which is technology agnostic.

I found JSON:API to be a great starting point, especially for small teams that want to get started right away. You can either adopt it or use it as a guideline for all the topics you need to consider.

https://jsonapi.org/format/

The Little Manual of API design

You can read it in an hour or two. It cover a lot of things that you should consider

Check out Google AIP

https://google.aip.dev/general

Do people still design rest-ful APIs? I often find I end up needing to do RPC-like things that make the API end up as a weird hybrid. I'm on the verge of abandoning the idea of trying to be rest-ful at all, so it's less incohesive.

I don't have any book recommendations to make since API design is more art than science. As such I'd recommend that you beta test the API (route names, payloads, etc) with a few potential users to gauge durability and the ease with which users can intuit. The last thing you want is to release new version quickly or to require users to always refer to your documentation.

Some of these problems can be solved with an SDK (highly recommend, as it can greatly improve developer experience especially in a modern text editor or IDE) or switching to GraphQL (not without its own problems).

If you use gRPC, I think you can see Google API Design [1] useful.

[1] https://cloud.google.com/apis/design

Consumer centric API design

https://github.com/tlhunter/consumer-centric-api-design

This book is really good: https://www.manning.com/books/the-design-of-web-apis

It even spends the first few chapters talking about API design in general (not just for REST) with really great, intuitive examples.

Please check "The C Interfaces and Implementations" book by David Hanson [1]. Someone has implemented the concept using his library that you can check and use [2].

Another excellent reference is the "The Linux Programming Interface" book by Michael Kerrisk that documents most of the API available under Linux [3].

[1]https://www.amazon.com/dp/0201498413

[2]https://github.com/gon1332/gonlibs

[3]https://www.amazon.com/Linux-Programming-Interface-System-Ha...

API design in C++ by Martin Reddy is a good text.

Maybe Lauret's The Design of Web APIs? [0]

[0]: https://www.manning.com/books/the-design-of-web-apis

Ebook from APIGee is pretty good, at least for me.

https://pages.apigee.com/web-api-design-register.html

Great recommendations! For another perspective, I'd add O'Reilly's "Continuous API Management" with some chapters around designing APIs as products and suggestions around how to implement a lifecycle. Also, strictly for design I'd also do what was suggested here and check API design guidelines from several sources. I like the Adidas one.

I really liked: The REST API Design Handbook by George Reese.

It is everything you need to know and thinks about the angle of the people who need to consume your API. Quick read too.

https://www.amazon.com/REST-API-Design-Handbook-ebook/dp/B00...

I analyzed 24 blog posts on API design (rest/graphql/rpc) and compiled a list of the books they recommended (sorted by the most popular ones first) https://www.readthistwice.com/lists/best-api-design-books.

Ignore the fact that this is a book about .NET, it's an excellent source of wisdom about the design of APIs:

https://www.amazon.com/dp/0321545613/ref=cm_sw_r_cp_apa_i_wn...

Not a book, but the best advice on API design I've ever seen was in 2004 by Casey Muratori on his talk "Designing and Evaluating Reusable Components".

https://www.youtube.com/watch?v=ZQ5_u8Lgvyk

Not a book, but this is a great talk about [How to Design Great APIs - Parse Developer Day 2013](https://www.youtube.com/watch?v=qCdpTji8nxo)

I like Framework Design Guidelines by Cwalina, Barton, and Abrams. The 3rd edition was recently released.

It's targeted at developing .NET frameworks with a broad audience so some of the guidelines aren't appropriate for internal APIs or applications.

Casey Muratori (Rad Game Tools, Handmade Hero) talk from 2004 covers reusability and design for ease of use.

https://caseymuratori.com/blog_0024

I wrote a popular blog post on this one:

https://www.vinaysahni.com/best-practices-for-a-pragmatic-re...

Moesif has many free resources for API design, development, and maintenence.

https://www.moesif.com/blog/api-guide/

https://github.com/microsoft/api-guidelines

REST API guidelines from Microsoft

for REST APIs, https://apisyouwonthate.com/books/build-apis-you-wont-hate book is my recommendation if you haven't read it already. I read it as a beginner, so it was kind of an eye opener for me on why we should do things a certain way when it comes to API.

Google published their guidelines for designing APIs [0]

[0] https://cloud.google.com/apis/design

Sure, read some books.

But know that they're all wrong. Some fatally.

The best you can do, ever, is to be consistent. So pick a style and stick to it. Honor the principle of least astonishment.