Hacker News new | comments | show | ask | jobs | submit login
Ask HN: What are good reads for designing APIs?
319 points by adnanh on Aug 10, 2016 | hide | past | web | favorite | 96 comments

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.

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

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


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:


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

[2] http://web.archive.org/web/20090520234149/http://chaos.troll...

Agreed. Find APIs you like to work with, think about WHY you like to work with them.

People get into really philosophical discussions around versioning, resource structure, etc... but in reality think about what makes you like the APIs you like over another alternative. Then think about what you would do to make it even easier to use/integrate with.

There also with some APIs is the tradeoff of easy integration and long-term flexibility.. things like that.

On that point, after you've read whichever of the many great recommendations you end up reading, don't get discouraged if you end up having to scrap the first several APIs you build. Part of the reason building APIs is so opinionated is that it's so difficult to do it well. Look at the API documentation for a bunch of different Google projects. Some of them are absolutely abominable. Others are quite good. Algolia has great documentation. When you get it wrong, you'll know. And that's all you really need to make sure you do better next time.

I really enjoy working with Twilio's API [0]. Their documentation is great. It includes an ample number of examples. The API is also extremely easy to use.

[0] https://www.twilio.com/docs/api/rest

lets look at how not to design an http API

Care to elaborate?

spot on my friend !!

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

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)

I am not familiar with GraphQL and my APIs are serving only a handful of people. I do have one suggestion: write a really really good client library for your user.

This eventually can become the basis of your test harness. In fact, every time I write my tests, I end up writing a client library...

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.

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

Wouldn't most people disagree with: "not `/posts/343/comments` but `/comments?post_id=232`"?

This is one issue I struggled with in my last API design. I generally like the /comments?post_id=232 format but in many cases it's not intuitive. Especially when the sub-resource (i.e. comments) is only ever referenced in with a parent resource (i.e. posts).

This is a bit of a contrived example but with a structure like /comments?post_id=232, a developer might mistakenly assume comments are independent resources and not explicitly tied to posts when, in reality, there are can be no comments without posts. In this case, /posts/343/comments is much more intuitive.

The way we ended up handling it was forcing ourselves to limit sub-resources to a maximum of 1 level deep. So /posts/343/comments was allowable but something like /posts/343/comments/23/author was not allowed.

In my view, arbitrary limits are also not too intuitive :)

Problem with nesting is that very rarely your resource classes will make an acyclic graph. Even in your example '/posts/343/comments/23/author' resource class AUTHOR may be a child of either comment or the post itself. And if a user wants to view all posts by particular author? Intuitive use might as well be '/posts/343/comments/23/author/posts/123/comments' ad infinitum :)

Such problems can be solved by providing an endpoint for each distinct resource class and making it search provider. In your example case 3 endpoints are needed: /post, /comment, /author, all accepting other two as search parameters, e.g. /author?comment=123456 or /author?comments|id=123456 (inspired by FHIR).

my reasoning:

you end up w/ a lot of filters very quickly and related post id will be just one of them

also linking it to another resource usually involved expecting defaults (default ordering, default display, pagination etc)

if you stay "flat" this tends to be less of an issue when usecases become more complex

Probably yes, the former not only "looks better", but is possibly easier to use in a view. Just spawn two delegates with `$post_path` and `pathcat($post_path, 'comments')` and be done with it.

However, the argument being made here is that you may not want to expose post comments as sub-resource of a particular post, but rather as completely separate resource.

And there is a point to that. Suppose you serve the post content as a static content, and comments from some application (octopress + disqus style). The latter format allows you to route anything matching `^/posts/(.*)` directly at web server level without touching application server at all. If you decided to use the former, then your infrastructure becomes dependent on your API structure. Not very nice :)

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

Until you hear from an iOS developer that it is a huge pain trying to figure out if the user has left a comment on an item or not and including this little flag would save tons of time.

client lib code is never the issue. usually scaling or breaking contracts is

you can just add it as separate key (similar how you embed eg user objects)

``` posts: {…} interactions: { commented_on_posts: [1212,12,1212,121] } ```

btw most people over estimate this problem the _total_ amount of user interactions is usually very small

in almost all cases you could download it once at boot for the user.

Good ideas, thanks!

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



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

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

As long as they adhere to the second part of their slogan, and "don't break [the prior versions of] [their] API", it's great.

Why are they versioning using dates? I know you probably wouldn't want to deploy a public API change more than once per day, but if version numbers are equally good why not give yourself the option? It also could lead to confusion about which API is newest due to UK vs US date formatting whereas a version number is unambiguous.

When I saw this thread title, I clicked and immediately Ctrl+F'd for 'amber.' Great read in general.

Amber rocks.

The Little Manual of API Design (Trolltech/Nokia): 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... https://www.youtube.com/watch?v=aAb7hSCtvGw

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,

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


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

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

2. Restful API using WebAPI - https://github.com/Microsoft/api-guidelines/blob/master/Guid...

3. API via dll - https://www.amazon.com/Framework-Design-Guidelines-Conventio...

I thought https://apisyouwonthate.com/ was pretty good, assuming REST API.

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

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)

+ Etsy

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

+1 for Vinay's guide - super helpful while planning your API structure in the early days.

A good read for API design is "The Little Manual of API Design": 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.

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.

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.

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.


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:


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.

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.

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


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.

this this this this this this

I cannot recommend this book enough. Read it, read it again, take in everything it is trying to say and try as hard as you can to understand it.

There is a whole world of awesome and tragically misunderstood tools in the book.

Casey Muratori - Designing and Evaluating Reusable Components


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.


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.


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

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.

Definitely, it is a great read.

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.

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

and the accompanying slides: http://static.googleusercontent.com/media/research.google.co...

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

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



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

Aside from Vinay's guide that has already been mentioned - http://www.vinaysahni.com/best-practices-for-a-pragmatic-res...

There is also this Medium post: https://bradfults.com/the-best-api-documentation-b9e46400379...

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

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

Agree on all accounts.

I'm horribly biased as one of the co-authors, but check out: 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.

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.

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/

Web API design by Apigee - https://drive.google.com/open?id=0B8qU9uFznmLsdFBHS1I2c1ZLRk...

Restful service design - https://drive.google.com/open?id=0B8qU9uFznmLsUEZ3TEFMbDZQcU...

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

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

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 "FK 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.

Good documentation is a key part

- Good summary of best practices for documentation: https://bocoup.com/weblog/documenting-your-api

- Tips for good api doc design: http://blog.parse.com/learn/engineering/designing-great-api-...

A cow helped me understand idempotency. :D http://www.restapitutorial.com/

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:


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


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:


I found Apigee's API design eBook really useful:


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

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.

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

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

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

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


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

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

Terrible API: BioTrackTHC

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

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


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.

Definitely http://swagger.io/, supported by AWS as well.

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.

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

Check out http://raml.org/

Any good online courses?

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

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact