
Ask HN: Suggestions for books about API design? - mcrittenden
In my case I&#x27;m specifically building a REST API with Lambda, but I&#x27;d be interested in any API design books you found valuable.
======
pixelmonkey
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...](https://twitter.com/amontalenti/status/1260030567501840386?s=19)

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](https://www.parse.ly/help/api/restful-apis)

~~~
dullgiulio
I really cannot agree with the "just use GET" suggestion. GET must not be used
for actions that modify the data server-side. Also, POST and PUT means some
action is or is not idempotent.

Using different methods than GET is easy in the browser (easier than JSON-P)
and avoids a huge class of problems that come with abusing GET.

~~~
pixelmonkey
Yes, honestly this was written at a time when browsers (specifically, the XHR
API) did not support non-GET requests reliably at all (e.g. pre-CORS), so
there was no other option. (And once you publish an API, it's hard to change.)
You're right that today there is better support for POST/PUT, although there
might still be some issues lurking in the corners.

~~~
pvg
I don't think there's ever been a time browsers haven't reliably supported
POST.

~~~
082349872349872
I dimly recall a pre-form web, but it could easily be they just took over a
little-used Berners-Lee verb. (For instance, PUT support was atrocious for a
while.)

~~~
pixelmonkey
This is not about pre-form web. It's about pre-CORS web. Which is pretty
recent web. CORS was "widely & properly" supported by "recently released"
browsers around 2012-2013. Of course it's only as of very recently that you
could safely assume 2010-2013 browser versions were completely out of
circulation.

~~~
082349872349872
My bad; hadn't parent'ed enough, and the "using different methods than GET"
clarification would not have been anachronistic even in the previous century.

------
riwsky
Don Norman’s “The Design of Everyday Things”
([https://en.m.wikipedia.org/wiki/The_Design_of_Everyday_Thing...](https://en.m.wikipedia.org/wiki/The_Design_of_Everyday_Things)).
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.

~~~
spectramax
Yep, I second this. Don Norman _really_ and _truly_ understood the user in the
deepest way. It’s hard to find people like him who put their entire
consciousness in the shoes of the user, simulate what the user goes through
when interacting with the world and provide insights about how, we the
designers, on the opposite aisle think about design as not some aesthetic shit
but as a tool to solve problems.

Design and designers, vast majority of them are chasing aesthetics and trends.
Just go on Behance to see it for yourself.

~~~
davidivadavid
That's about as accurate a judgment on designers as calling programmers "code
monkeys."

Follow a couple designers on Twitter for a few weeks and you're almost
guaranteed to see someone quote Steve Jobs saying "Design is not just what it
looks like and feels like. Design is how it works."

All designers know that.

~~~
eska
To be fair, most programmers are code monkeys. But that's true for most people
in any profession. It's not a fair comparison to compare the average worker to
workers of excellence.

------
sandGorgon
Stripe blog posts are unparalleled

[https://stripe.com/blog/api-versioning](https://stripe.com/blog/api-
versioning)

[https://stripe.com/blog/idempotency](https://stripe.com/blog/idempotency)

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

------
danpalmer
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](https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm)

Chapter introducing REST:
[https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)

~~~
tarsinge
Do you think it's still relevant for modern client web apps / data backend (I
have no doubt it is for websites though).

~~~
danpalmer
REST is fundamentally about how do to useful communication between networked
services. I'd recommend reading the paper for anyone doing anything related to
that. I happen to use GraphQL at work, but that doesn't stop me from learning
a lot from the paper.

------
majkinetor
[https://apisyouwonthate.com](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](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...](https://restful-api-
design.readthedocs.io/en/latest/intro.html)

Manning has a solid books on topic:

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

[https://www.manning.com/books/api-design-
patterns](https://www.manning.com/books/api-design-patterns)

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

------
disposedtrolley
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/](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.

------
tj612
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...](https://www.oreilly.com/library/view/rest-api-
design/9781449317904/)

~~~
pugworthy
Agreed. Simple and clean, with an approach that makes for consistency.

------
hoorayimhelping
Domain Driven Design: [https://smile.amazon.com/Domain-Driven-Design-Tackling-
Compl...](https://smile.amazon.com/Domain-Driven-Design-Tackling-Complexity-
Software/dp/0321125215)

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.

------
yhoiseth
Not a book, but the current issue of
[https://increment.com/](https://increment.com/) is about APIs.

~~~
cpeterso
I hadn't heard of Increment before. They have some very interesting articles!
I like how they group a number of articles from different authors on a related
topic. Thanks for sharing.

------
makstaks
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/](https://jsonapi.org/format/)

------
rantwasp
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

~~~
albertop
Which one? There is 20 of them.

~~~
docwicking
I was looking for this specific title in the suggestions, as I got this
recommended myself a few years back. If we have the same little manual in
mind, it's by Jasmin Blanchette. I can't say anything about the other 19.

------
thanhhaimai
Check out Google AIP

[https://google.aip.dev/general](https://google.aip.dev/general)

------
timclark
A philosophy of software design - John Ousterhout

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

~~~
kalecserk
The most influential technical book I have read over the past 10 years for
sure. The author guides the reader though the process of managing complexity
with some intriguing concepts such as "Define errors out of existence" and
"Deep modules". I definitely recommend it.

------
beaker52
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.

~~~
mattbillenstein
Honestly, prefer GraphQL -- it's more like designing a schema which you may
already be doing in your database anyway. The client decides which data in
what shape it fetches.

~~~
dehrmann
If you're designing an internal API to power a rich client app, yes. If you're
designing an API for developers to interface with you SaaS, plain old HTTP is
a better choice, even if it's only RESTful in a hand wavy sense.

~~~
mattbillenstein
Yeah, agree - if your product is an api, I'd have REST first, then graphql
later perhaps if people are interested in that.

------
yawboakye
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).

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

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

------
nicwest
Consumer centric API design

[https://github.com/tlhunter/consumer-centric-api-
design](https://github.com/tlhunter/consumer-centric-api-design)

~~~
PaulStatezny
I just read through a good chunk of this, hoping it'd be a good resource.

There's a lot of good stuff in here:

\- Higher level than a spec, but still detailed.

\- He outlines the anatomy of an HTTP request and gives examples.

\- Lots of good suggestions of conventions and rules of thumb, e.g. for URL
structure and naming.

\- Good demonstration of why using fitting HTTP verbs is important. Explains
idempotent and safe.

On the flip side, his ethos isn't the best at points, he presents some
subjective takes as fact, and even includes some plain errors against the
specification.

For example:

\- JSON keys should be snake cased, or camelCased "if you're one of _those_
people". (I'm a snake case guy, but really?)

\- Return a 400 if there are any problems with the request. (400 explicitly
means request body can't be parsed, e.g. syntax error in your JSON. The spec
isn't perfect, but 422 is often more fitting if the consumer input didn't pass
validation. Either way 400 clearly violates the spec.)

\- He misses the nuance of what PUT is in the spec. You're saying "store this
resource at this URL". Not technically update. Although in practice it's
usually update, and I'm sure this point will be viewed as pedantic by many.

Overall a decent resource, but take it with a grain of salt.

------
dudul
This book is really good: [https://www.manning.com/books/the-design-of-web-
apis](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.

------
teleforce
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](https://www.amazon.com/dp/0201498413)

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

[3][https://www.amazon.com/Linux-Programming-Interface-System-
Ha...](https://www.amazon.com/Linux-Programming-Interface-System-
Handbook/dp/1593272200)

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

~~~
andi999
Agree. It is very good, but I think thee things he is concerned with are very
c++ specific.

------
HuShifang
Maybe Lauret's _The Design of Web APIs_? [0]

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

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

[https://pages.apigee.com/web-api-design-
register.html](https://pages.apigee.com/web-api-design-register.html)

------
manuu80
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.

------
vhpoet
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](https://www.readthistwice.com/lists/best-api-design-books).

------
rajvosa07
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...](https://www.amazon.com/REST-API-Design-Handbook-
ebook/dp/B00890OBFI)

------
idan
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...](https://www.amazon.com/dp/0321545613/ref=cm_sw_r_cp_apa_i_wnivFbAXFCB24)

------
shivenigma
for REST APIs, [https://apisyouwonthate.com/books/build-apis-you-wont-
hate](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.

------
matiasfernandez
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](https://www.youtube.com/watch?v=ZQ5_u8Lgvyk)

------
thallavajhula
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](https://www.youtube.com/watch?v=qCdpTji8nxo))

------
tjalfi
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.

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

[https://caseymuratori.com/blog_0024](https://caseymuratori.com/blog_0024)

------
veesahni
I wrote a popular blog post on this one:

[https://www.vinaysahni.com/best-practices-for-a-pragmatic-
re...](https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api)

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

[https://www.moesif.com/blog/api-guide/](https://www.moesif.com/blog/api-
guide/)

------
ayush--s
[https://github.com/microsoft/api-
guidelines](https://github.com/microsoft/api-guidelines)

REST API guidelines from Microsoft

------
simonpure
Google published their guidelines for designing APIs [0]

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

------
specialist
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.

