Ask HN: What are good reads for designing APIs? - adnanh
======
ccallebs
You'll notice in this thread that (at 9 comments in) there are no repeated
recommendations. If the question was "What are some good reads for learning
about algorithms?" you'd probably see the same handful of books being praised
by everyone.

Don't be overwhelmed by this though -- API design isn't an exact science. It's
also very opinionated.

Personally, I would just start reading actual API documentation (GitHub is a
great place to start -- their API is a joy to work with). Find things you like
and don't like about it and try to figure out why those decisions were made.

~~~
derefr
> I would just start reading actual API documentation (GitHub is a great place
> to start -- their API is a joy to work with)

This would be a good related subthread: links to API docs for what people
consider to be both great, and terrible, APIs.

~~~
OJFord
> This would be a good related subthread: links to API docs > for what people
> consider to be both great, and terrible, > APIs.

At least the great part has happened:

[https://news.ycombinator.com/item?id=867972](https://news.ycombinator.com/item?id=867972)

There was one _much_ more recently (a week or two ago), but funnily enough the
only one I can find is ~2.5k days old..

Related - best documented:

[https://news.ycombinator.com/item?id=6224155](https://news.ycombinator.com/item?id=6224155)

~~~
puddintane
I liked this recommendation a lot by vibhavs [1] (in your first link). Found
the pdf thru Wayback machine [2]. Had a lot of really good tips to keep in
mind.

[1]
[https://news.ycombinator.com/item?id=868102](https://news.ycombinator.com/item?id=868102)

[2]
[http://web.archive.org/web/20090520234149/http://chaos.troll...](http://web.archive.org/web/20090520234149/http://chaos.troll.no/~shausman/api-
design/api-design.pdf)

------
andreasklinger
When doing my last bigger API i read every recommendation. Still learned a
lot.

Everyone has different recommendations - dont get discouraged by this.

Make sure also to look into newer standards like JsonAPI if they are suitable
- last time i tried to use it the tooling around it was still not strong
enough and i decided to go w/ simpler custom api.

Assuming it has to be a restful api (vs graphql) and assuming you want to
create an api for multiple kinds of clients (that's the the harder part) -
Here my personal TL;DR:

\- Autogenerate your docs with your tests

\- Do versioning in URL (easier to route/cache/etc)

\- Worry about caching (a lot)

\- Personalized info only in isolated namespace, rest is fully cacheable

\- Never embed personalized information (eg not `{ post: { user_has_commented:
true } }`

\- Never nest data (not `post: { author: { … } }` but reference only `post:
{author_id: …}`)

\- Embed referenced objects only by whitelist

\- Never nest routes (not `/posts/343/comments` but `/comments?post_id=232`)
filtering tends to become more complex

\- Use public feedback tools (eg github issues) for your user
questions/complains - so it can become searchable for people with similar
problems

hth - happy to answer some of those in detail if useful

As said - highly subjective opinions - i am sure others might disagree w/ some
of the points

~~~
emilsedgh
_Never nest data (not `post: { author: { … } }` but reference only `post:
{author_id: …}`)_

I'm creating a huge API on my dayjob and we have nested A LOT. So many levels
of nesting, the responses have become too big.

Yet, the clients refuse to call additional endpoints and always insist on
this. And it _does_ make sense for them to make 1 call and retrieve all
information they need.

How does everyone handle this on REST?

(I know GraphQL is a solution.I'm wondering how people use REST API's)

~~~
biot
If you must, serve up the authors as an array that is a sibling of the posts
array. So if you have 100 posts written by only 3 authors, you have:

    
    
      { 
        posts: [ /* 100 records */ ],
        authors: [ /* 3 records */ ] 
      }
    

Each post references the author by ID only and all required data is sent in
one API call.

~~~
_asummers
Even better: make authors be a map of ID to author so you can get fast lookup
by ID when you need it.

------
lnikkila
I really liked Building Stripe’s API and it’s sequel, Move fast, don’t break
your API:

[http://amberonrails.com/building-stripes-
api/](http://amberonrails.com/building-stripes-api/)

[http://amberonrails.com/move-fast-dont-break-your-
api/](http://amberonrails.com/move-fast-dont-break-your-api/)

~~~
pbreit
The amount of versioning that Stripe does makes nervous. Is that a good
practice?

~~~
Silhouette
Personally the versioning and backward incompatibility don't concern me in
themselves, as long as integrations with older API versions are also fully
supported indefinitely and there is a clear and safe path to upgrade.

In Stripe's case, I normally find an initial integration is a better
experience than most payment services. The API is reasonably designed and well
documented.

However, I also find Stripe integrations are effectively impossible to
maintain or update over time. Older API versions aren't documented anywhere I
can find, only the current one. There are decent changelogs with warnings of
incompatibilities, but you can't write an automated integration test suite.
I've never found any documentation that explains how their versioning actually
works, what is affected, and how to revert if you update and there's a
problem.

In practice, that means older versions of the API aren't fully supported
indefinitely, nor is there a safe, systematic path to manage an upgrade to a
newer API version. For that reason, we normally treat Stripe integrations as
write-only code, where once you've got something written, tested and into
production, it's never touched again (short of a serious security issue or the
like, obviously).

------
esja
The Little Manual of API Design (Trolltech/Nokia): [http://people.mpi-
inf.mpg.de/~jblanche/api-design.pdf](http://people.mpi-
inf.mpg.de/~jblanche/api-design.pdf)

How to Design a Good API and Why it Matters (Josh Bloch):
[http://static.googleusercontent.com/media/research.google.co...](http://static.googleusercontent.com/media/research.google.com/en//pubs/archive/32713.pdf)
[https://www.youtube.com/watch?v=aAb7hSCtvGw](https://www.youtube.com/watch?v=aAb7hSCtvGw)

~~~
hinkley
Ugh. Can someone please point me to a good API designed by Josh Bloch? The
handful I know of have all been a giant pain in my backside.

He keeps writing like he's an expert and I am still waiting for evidence to
back that up,

------
hbcondo714
Microsoft's REST API Guidelines are newly hosted on Github and were posted
here last month with plenty of discussion:

[https://news.ycombinator.com/item?id=12122828](https://news.ycombinator.com/item?id=12122828)

------
niftich
I recommend this physical book: 'RESTful Web Services Cookbook'. It walks you
though the rationale behind HTTP APIs and progressively using more and more of
HTTP's features to build a sophisticated but elegant API.

[1]
[http://shop.oreilly.com/product/9780596801694.do](http://shop.oreilly.com/product/9780596801694.do)

------
mandeepj
API could be in any form - be it a dll lib, wcf or rest so I am pasting a
resource for each.

1\. Restful API with WCF - [https://msdn.microsoft.com/en-
us/library/dd203052.aspx](https://msdn.microsoft.com/en-
us/library/dd203052.aspx)

2\. Restful API using WebAPI - [https://github.com/Microsoft/api-
guidelines/blob/master/Guid...](https://github.com/Microsoft/api-
guidelines/blob/master/Guidelines.md)

3\. API via dll - [https://www.amazon.com/Framework-Design-Guidelines-
Conventio...](https://www.amazon.com/Framework-Design-Guidelines-Conventions-
Libraries/dp/0321545613/ref=sr_1_1?s=books&ie=UTF8&qid=1470852593&sr=1-1&keywords=framework+design+guidelines)

------
mordocai
I thought [https://apisyouwonthate.com/](https://apisyouwonthate.com/) was
pretty good, assuming REST API.

------
omgitstom
This question is a little vague. My assumption is you mean a REST API.

This is a must watch and encapsulates good design and theory:
[https://www.youtube.com/watch?v=hdSrT4yjS1g](https://www.youtube.com/watch?v=hdSrT4yjS1g)

Good API design, if you are trying to learn from zero, comes from learning
from good examples.

These are some of my favorites APIs by design

\+ Stripe

\+ Twilio

\+ Slack

\+ Stormpath (fd: I work here)

There is a lot of work that goes around the API design to make it a great API
(examples, documentation, live samples, etc)

~~~
olkid
\+ Etsy

------
codegeek
[http://www.vinaysahni.com/best-practices-for-a-pragmatic-
res...](http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api)

~~~
jgrandelli
+1 for this "guide." It is super easy to digest and nice to have as a
reference. Where some books might be denser and be full of more information
and details, this post was full of great bits of info that could easily be
referenced back to.

------
gabriel
A good read for API design is "The Little Manual of API Design":
[http://www4.in.tum.de/~blanchet/api-
design.pdf](http://www4.in.tum.de/~blanchet/api-design.pdf)

It falls into the category of non-web API. It's a good read and I think it
carries over to web APIs quite well.

------
johnwheeler
Times really do change very fast.

Many of the comments here take API to mean an HTTP exposed API (REST), but API
stands for "Application Programming Interface"

It is much more generalized than APIs designed for HTTP consumption.

~~~
niftich
I think in this case we all had to infer context where none was provided, but
you're right that the meaning has drifted.

These days the unit of work is very often some HTTP-exposed service rather
than a platform library, or an interface to hardware or the like. But, I'll
join your point and say there aren't too many (recent) generic resources about
how to design non-HTTP APIs, since the idioms and patterns tend to be
language-specific.

------
tengbretson
You should checkout the ØMQ guide. They do such a good job of first defining
the problem space, and then establishing the design patterns they use to solve
it.

The code examples almost become irrelevant because they make the patterns so
clear.

[http://zguide.zeromq.org/page:all](http://zguide.zeromq.org/page:all)

------
JimDabell
I think it depends on what type of API you'd like to design.

If you're talking about REST APIs, then the best book I've come across is
RESTful Web APIs by Leonard Richardson and Mike Amundsen:

[http://restfulwebapis.org/](http://restfulwebapis.org/)

It actually shows you how to do REST properly, not that shoddy knock-off REST
that some people push, where you have to document all your URI structures and
hard-code them in your clients. There's solid examples that you build upon
throughout each chapter, and jumping off points to standardisation work like
JSON-LD etc.

~~~
MichaelGG
Why should anyone care about doing "REST properly"? I've never seen a
convincing argument. I've used REST and "shoddy REST" and haven't seen much
indicators in quality one way or another. In fact, far beyond the actual
design is the question if they provide client code. That makes so much more of
an impact.

Indeed the only real negative I've seen is people going out of their way to
make it REST and in the process adding needless details, or requiring me to
set a bunch of options on my HTTP request. Hint: setting a bunch of headers
and a verb is not easier than passing some querystring params.

~~~
fzilla
The HTTP spec exists to help you interact with resources in a specific way.

In my experience, the "shoddy REST" the original commenter is talking about
usually involves developers ignoring the design principles behind HTTP and
trying to pretend like they can't or don't need to map their organization's
domain model to HTTP's resource model. This typically happens because they
either don't understand how to do this, don't have time, or think that the
effort involved to rethink their model isn't worth the effort.

What they end up with is a cobbled-together mess of endpoints that perform
unintuitively specific functions constructed in the language of a system that
wasn't designed to work that way.

A really good example of this might be a blog API. Which is better?

POST /entries/<id>/publish

or

PATCH /entries/<id> with a request body of { published: true }

The POST seems more immediately intuitive __to the API developers __, because
they can just add all publish-related tasks in the publish route handler or
controller and call it a day. But the PATCH is more immediately intuitive __to
the API consumer __, because they probably understand that entries have a
"published" field (this gets more into hypermedia and semantics and beyond the
scope of this post), and that PATCH allows them to change a field, and that if
"published" is true then the entry is live.

A good analogy is trying to construct your own special-purpose language using
English words, but with totally new meanings and purposes for each word, then
expecting to communicate with others in this language. It superficially looks
like English, but cannot be understood without volumes of documentation
explaining how it is different.

------
joeld42
Casey Muratori - Designing and Evaluating Reusable Components

[https://mollyrocket.com/casey/stream_0028.html](https://mollyrocket.com/casey/stream_0028.html)

------
idan
Though it's somewhat dated and C# oriented, the really, really fantastic
Framework Design Guidelines by Brad Abrams and Krzysztof Cwalina is a
thoughtful treatise on designing usable APIs. A lot of the things I read in
there still resonate with me almost a decade later.

[https://www.amazon.co.uk/Framework-Design-Guidelines-
Convent...](https://www.amazon.co.uk/Framework-Design-Guidelines-Conventions-
Development/dp/0321545613)

------
rcpt
I found this SIGCHI paper from Google to be an interesting read. Abstract:

>The number of APIs produced by Google’s various business units grew at an
astounding rate over the last decade, the result of which was a user
experience containing wild inconsistencies and usability problems. There was
no single issue that dominated the usability problems; rather, users suffered
a death from a thousand papercuts. A lightweight, scalable, distributed design
review process was put into place that has improved our APIs and the efficacy
of our many API designers. Challenges remain, but the API design reviews at
scale program has started successfully.

[http://delivery.acm.org/10.1145/2860000/2851602/ea849-macvea...](http://delivery.acm.org/10.1145/2860000/2851602/ea849-macvean.pdf?ip=98.7.42.85&id=2851602&acc=OA&key=4D4702B0C3E38B35%2E4D4702B0C3E38B35%2E4D4702B0C3E38B35%2E3DF11CAF58636DA7&CFID=654192422&CFTOKEN=53191991&__acm__=1470883827_466b523ae56bf8bb522ce745f99241a0)

------
jbox
Heroku's Interagent is a set of practical guidelines for building APIs based
on their Platform API: [https://github.com/interagent/http-api-
design](https://github.com/interagent/http-api-design)

------
danpalmer
I'd recommend the original REST thesis from Roy Fielding. It's a bit lower
level than most of the other things mentioned here, but helps get a good
feeling for what is important to achieve in a RESTful web service.

~~~
jamesxv7
Definitely, it is a great read.

------
aeijdenberg
I think the single best thing an API designer should do is write a getting
started guide with working sample code for the API they are producing.

On my last project I found myself revising the API surface twice as a result
of doing so.

------
neves
Don't miss Joshua Bloch (from "Effective Java" fame) great presentation: How
to design a good API and why it matters
[https://www.youtube.com/watch?v=aAb7hSCtvGw](https://www.youtube.com/watch?v=aAb7hSCtvGw)

and the accompanying slides:
[http://static.googleusercontent.com/media/research.google.co...](http://static.googleusercontent.com/media/research.google.com/pt-
BR//pubs/archive/32713.pdf)

~~~
philbo
+1, strongly agree.

I've recommended this talk to numerous colleagues over the years, always with
extremely positive feedback. And I've re-watched it myself 3 or 4 times as a
refresher before starting out on a new API.

It's easily in my top ten favourite programming talks. If anyone hasn't
watched it, I can't recommend it highly enough.

------
cesarb
I always liked Rusty's list on making an API "hard to misuse" (and its
followup):

[https://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html](https://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html)

[https://ozlabs.org/~rusty/index.cgi/tech/2008-04-01.html](https://ozlabs.org/~rusty/index.cgi/tech/2008-04-01.html)

~~~
spankalee
Came here to post Rusty's API Design Manifesto too :)

This page is a more concise overview of the levels: [http://sweng.the-
davies.net/Home/rustys-api-design-manifesto](http://sweng.the-
davies.net/Home/rustys-api-design-manifesto)

------
cyberferret
Aside from Vinay's guide that has already been mentioned -
[http://www.vinaysahni.com/best-practices-for-a-pragmatic-
res...](http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api)

There is also this Medium post: [https://bradfults.com/the-best-api-
documentation-b9e46400379...](https://bradfults.com/the-best-api-
documentation-b9e46400379a#.am4n12emj)

------
avicoder
Check this one: Build APIs You Won't Hate - Phil Sturgeon

~~~
trwhite
I second this. Great read if you want a better understanding of design your
APIs.

------
caseysoftware
I'm horribly biased as one of the co-authors, but check out:
[http://TheAPIDesignBook.com](http://TheAPIDesignBook.com)

It documents a number of things we've learned building, using, and supporting
APIs at Twilio, major banks, major hotel chains, and others. It's 100% driven
by practices in the wild, not academic or theoretical info.

~~~
Perihelion
Having just picked this one up, I can confirm it's actually worth a read. It's
short but full of information that will help you design better APIs even if
you've already done it.

------
rudedogg
I know you asked for books, but if you are an Apple Developer they had a
really good talk at WWDC about API design called "Swift API Design
Guidelines".

The docs have similar content: [https://swift.org/documentation/api-design-
guidelines/](https://swift.org/documentation/api-design-guidelines/)

------
wooptoo
Web API design by Apigee -
[https://drive.google.com/open?id=0B8qU9uFznmLsdFBHS1I2c1ZLRk...](https://drive.google.com/open?id=0B8qU9uFznmLsdFBHS1I2c1ZLRkE)

Restful service design -
[https://drive.google.com/open?id=0B8qU9uFznmLsUEZ3TEFMbDZQcU...](https://drive.google.com/open?id=0B8qU9uFznmLsUEZ3TEFMbDZQcUE)

Notes on RESTful APIs - [http://wooptoo.com/blog/notes-on-restful-
apis/](http://wooptoo.com/blog/notes-on-restful-apis/) \- written by yours
truly some years ago

------
solidgumby
This is my goto resource when the team starts bike-shedding on implementation
details. [http://jsonapi.org/](http://jsonapi.org/)

------
erikb
You can't learn that in a book. Use other ppls APIs, read other people's APIs,
design own APIs, overcome the desire to say "F __K U " to everybody who
criticises your APIs, edit your APIs, rinse&repeat.

It becomes interesting once you start to use/read "hard" or "shitty" APIs. You
may discover that many of them aren't either of their given labels, but that
they solve really complex problems, that can't be solved (even) more
intuitively.

------
abhip
Good documentation is a key part

\- Good summary of best practices for documentation:
[https://bocoup.com/weblog/documenting-your-
api](https://bocoup.com/weblog/documenting-your-api)

\- Tips for good api doc design:
[http://blog.parse.com/learn/engineering/designing-great-
api-...](http://blog.parse.com/learn/engineering/designing-great-api-docs/)

------
Walkman
A cow helped me understand idempotency. :D
[http://www.restapitutorial.com/](http://www.restapitutorial.com/)

------
duncan_bayne
It's a bit meta, but consider that building a culture that supports good APIs
is every bit as important as the APIs themselves, and usually harder.

A good starting point in this area is Steve Yegge's famous platform rant:

[https://plus.google.com/+RipRowan/posts/eVeouesvaVX](https://plus.google.com/+RipRowan/posts/eVeouesvaVX)

------
b0sk
a bunch of API design guidelines flow from Scott Meyer's famous maxim "Make
interfaces easy to use correctly and hard to use incorrectly."

[http://www.aristeia.com/Papers/IEEE_Software_JulAug_2004_rev...](http://www.aristeia.com/Papers/IEEE_Software_JulAug_2004_revised.htm)

------
yareally
I was always fond of the "how to GET a cup of coffee" article on REST and
APIs. I know it's been posted here in the past (how I found it), but for ease
of access:

[https://www.infoq.com/articles/webber-rest-
workflow](https://www.infoq.com/articles/webber-rest-workflow)

------
junto
I found Apigee's API design eBook really useful:

[http://apigee.com/about/resources/ebooks/web-api-
design](http://apigee.com/about/resources/ebooks/web-api-design)

I was impressed with the Rackspace Cloud API and documentation too. Especially
their authentication services.

------
danm07
The best thing to do is to start using API that other people have built. Try
getting the data, see where the bottlenecks/friction points are - what things
are clear and what things are not. This will put you in the shoes of someone
who will physically use one. Otherwise, its all conjecture.

------
pedritter
Write code that is easy to delete, not easy to extend.
[http://programmingisterrible.com/post/139222674273/write-
cod...](http://programmingisterrible.com/post/139222674273/write-code-that-is-
easy-to-delete-not-easy-to)

------
morenoh149
I asked myself this a couple of months back. Here's what I found
[http://harrymoreno.com/2016/03/31/API-design-link-
roundup.ht...](http://harrymoreno.com/2016/03/31/API-design-link-roundup.html)

------
mh8h
If you need programming APIs, and not necessarily REST, take a look at
"Practical API Design, Confessions of a Java Framework Architect":
[http://www.apress.com/9781430209737](http://www.apress.com/9781430209737)

------
dmreedy
I'm going to take the pretentious and predictable* route here and recommend
The Design of Everyday Things. It's not about REST APIs or whatever particular
instance you're after, but it is more philosophical about what APIs are.

*Like a freshman preaching Rand

------
Flenser
[https://github.com/SamHasler/Chrome-Bookmark-
Exports/blob/ma...](https://github.com/SamHasler/Chrome-Bookmark-
Exports/blob/master/rest-api.md#api-design)

------
ccleve
Apigee's book is great:

[https://pages.apigee.com/rs/apigee/images/api-design-
ebook-2...](https://pages.apigee.com/rs/apigee/images/api-design-
ebook-2012-03.pdf)

------
divkakwani
Have a look at Facebook's Graph API:
[https://developers.facebook.com/docs/graph-
api](https://developers.facebook.com/docs/graph-api)

------
azhenley
[http://apiusability.org/](http://apiusability.org/)

This page was started by a dozen or so researchers back in 2009 and has a list
of publications on the subject.

------
sigjuice
This book has been on my shelf since forever (my Amazon says Sep 2005) and
maybe I will actually read it someday :/

C Interfaces and Implementations: Techniques for Creating Reusable Software By
David R. Hanson

------
edoceo
Terrible API: BioTrackTHC

Read their stuff for what to NOT do. Use it for real torture.

------
pjmlp
For C++ APIs, "API Design for C++" from Martin Reddy:

[http://www.apibook.com/blog/](http://www.apibook.com/blog/)

------
smurfpandey
[https://github.com/interagent/http-api-
design](https://github.com/interagent/http-api-design)

------
enitihas
I think if you have the time you should read SICP. It is not just about APIs,
but my understanding of good APIs too increased a lot after reading this.

------
mchamati
Definitely [http://swagger.io/](http://swagger.io/), supported by AWS as well.

~~~
themihai
Last time I checked(about 6 -7 months ago) swagger was quite messy. I ended-up
with Hyper-Schema which proved simpler and better thought out.

------
rdsubhas
Teach a Dog to REST: Some great REST API patterns distilled into a simple
presentation [http://www.slideshare.net/landlessness/teach-a-dog-to-
rest](http://www.slideshare.net/landlessness/teach-a-dog-to-rest)

------
jrs235
[https://leanpub.com/restful-api-design](https://leanpub.com/restful-api-
design)

------
djuang1
Check out [http://raml.org/](http://raml.org/)

------
darkfishboat
Any good online courses?

