9 ms·

Ask HN: What are good reads for designing APIs?

319 points by adnanh 10y ago

avicoder 10y ago
Check this one: Build APIs You Won't Hate - Phil Sturgeon
- deleted 10y ago
  [deleted]
- trwhite 10y ago
  I second this. Great read if you want a better understanding of design your APIs.
- jmcharnes 10y ago
  Agree on all accounts.
enitihas 10y ago
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.
jrs235 10y ago
https://leanpub.com/restful-api-design https://leanpub.com/restful-api-design
hbcondo714 10y ago
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
codegeek 10y ago
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api http://www.vinaysahni.com/best-practices-for-a-pragmatic-res...
- jgrandelli 10y ago
  +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.
- cyberferret 10y ago
  +1 for Vinay's guide - super helpful while planning your API structure in the early days.
tengbretson 10y ago
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
ccleve 10y ago
Apigee's book is great: https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf https://pages.apigee.com/rs/apigee/images/api-design-ebook-2...
jbox 10y ago
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
esja 10y ago
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.com/en//pubs/archive/32713.pdf http://static.googleusercontent.com/media/research.google.co... https://www.youtube.com/watch?v=aAb7hSCtvGw https://www.youtube.com/watch?v=aAb7hSCtvGw
- hinkley 10y ago
  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,
smurfpandey 10y ago
https://github.com/interagent/http-api-design https://github.com/interagent/http-api-design
cesarb 10y ago
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 10y ago
  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
solidgumby 10y ago
This is my goto resource when the team starts bike-shedding on implementation details. http://jsonapi.org/ http://jsonapi.org/
ccallebs 10y ago
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.
- supergeek133 10y ago
  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.
- sd_sangit 10y ago
  spot on my friend !!
- cloudjacker 10y ago
  lets look at how not to design an http API
  - philgo20 10y ago
    Care to elaborate?
- levbrie 10y ago
  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.
deleted 10y ago
[deleted]
mchamati 10y ago
Definitely http://swagger.io/ http://swagger.io/, supported by AWS as well.
- themihai 10y ago
  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.
omgitstom 10y ago
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 10y ago
  + Etsy
divkakwani 10y ago
Have a look at Facebook's Graph API: https://developers.facebook.com/docs/graph-api https://developers.facebook.com/docs/graph-api
niftich 10y ago
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
danpalmer 10y ago
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 10y ago
  Definitely, it is a great read.
Walkman 10y ago
A cow helped me understand idempotency. :D http://www.restapitutorial.com/ http://www.restapitutorial.com/
johnwheeler 10y ago
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 10y ago
  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.
andreasklinger 10y ago
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
- pbreit 10y ago
  Wouldn't most people disagree with: "not `/posts/343/comments` but `/comments?post_id=232`"?
  - misterbwong 10y ago
    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.
dmreedy 10y ago
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
lnikkila 10y ago
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/
- niftylettuce 10y ago
  Amber rocks.
- pbreit 10y ago
  The amount of versioning that Stripe does makes nervous. Is that a good practice?
  - deleted 10y ago
    [deleted]
  - OJFord 10y ago
    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.
  - Silhouette 10y ago
    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).
joeld42 10y ago
Casey Muratori - Designing and Evaluating Reusable Components https://mollyrocket.com/casey/stream_0028.html https://mollyrocket.com/casey/stream_0028.html
neves 10y ago
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.com/pt-BR//pubs/archive/32713.pdf http://static.googleusercontent.com/media/research.google.co...
- philbo 10y ago
  +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.
JimDabell 10y ago
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.
- fzilla 10y ago
  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.
- MichaelGG 10y ago
  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 10y ago
    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.
djuang1 10y ago
Check out http://raml.org/ http://raml.org/
b0sk 10y ago
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_revised.htm http://www.aristeia.com/Papers/IEEE_Software_JulAug_2004_rev...
mordocai 10y ago
I thought https://apisyouwonthate.com/ https://apisyouwonthate.com/ was pretty good, assuming REST API.
mandeepj 10y ago
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/Guidelines.md https://github.com/Microsoft/api-guidelines/blob/master/Guid... 3. API via dll - 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 https://www.amazon.com/Framework-Design-Guidelines-Conventio...
mh8h 10y ago
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
rdsubhas 10y ago
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
pjmlp 10y ago
For C++ APIs, "API Design for C++" from Martin Reddy: http://www.apibook.com/blog/ http://www.apibook.com/blog/
idan 10y ago
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-Conventions-Development/dp/0321545613 https://www.amazon.co.uk/Framework-Design-Guidelines-Convent...
morenoh149 10y ago
I asked myself this a couple of months back. Here's what I found http://harrymoreno.com/2016/03/31/API-design-link-roundup.html http://harrymoreno.com/2016/03/31/API-design-link-roundup.ht...
darkfishboat 10y ago
Any good online courses?
gabriel 10y ago
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.
rudedogg 10y ago
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/
yareally 10y ago
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
abhip 10y ago
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-docs/ http://blog.parse.com/learn/engineering/designing-great-api-...
azhenley 10y ago
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.
aeijdenberg 10y ago
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.
caseysoftware 10y ago
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 10y ago
  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.
edoceo 10y ago
Terrible API: BioTrackTHC Read their stuff for what to NOT do. Use it for real torture.
pedritter 10y ago
Write code that is easy to delete, not easy to extend. http://programmingisterrible.com/post/139222674273/write-code-that-is-easy-to-delete-not-easy-to http://programmingisterrible.com/post/139222674273/write-cod...
duncan_bayne 10y ago
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
Flenser 10y ago
https://github.com/SamHasler/Chrome-Bookmark-Exports/blob/master/rest-api.md#api-design https://github.com/SamHasler/Chrome-Bookmark-Exports/blob/ma...
erikb 10y ago
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.
danm07 10y ago
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.
cyberferret 10y ago
Aside from Vinay's guide that has already been mentioned - http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api http://www.vinaysahni.com/best-practices-for-a-pragmatic-res... There is also this Medium post: https://bradfults.com/the-best-api-documentation-b9e46400379a#.am4n12emj https://bradfults.com/the-best-api-documentation-b9e46400379...
rcpt 10y ago
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-macvean.pdf?ip=98.7.42.85&id=2851602&acc=OA&key=4D4702B0C3E38B35%2E4D4702B0C3E38B35%2E4D4702B0C3E38B35%2E3DF11CAF58636DA7&CFID=654192422&CFTOKEN=53191991&__acm__=1470883827_466b523ae56bf8bb522ce745f99241a0 http://delivery.acm.org/10.1145/2860000/2851602/ea849-macvea...
junto 10y ago
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.
wooptoo 10y ago
Web API design by Apigee - https://drive.google.com/open?id=0B8qU9uFznmLsdFBHS1I2c1ZLRkE https://drive.google.com/open?id=0B8qU9uFznmLsdFBHS1I2c1ZLRk... Restful service design - https://drive.google.com/open?id=0B8qU9uFznmLsUEZ3TEFMbDZQcUE https://drive.google.com/open?id=0B8qU9uFznmLsUEZ3TEFMbDZQcU... 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
AndrejXY 10y ago
I liked this one: REST API Design Rulebook, Designing Consistent RESTful Web Service Interfaces, by Mark Masse http://shop.oreilly.com/product/0636920021575.do http://shop.oreilly.com/product/0636920021575.do
sigjuice 10y ago
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

319 points by adnanh 10y ago

avicoder 10y ago

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

deleted 10y ago
[deleted]
trwhite 10y ago
I second this. Great read if you want a better understanding of design your APIs.
jmcharnes 10y ago
Agree on all accounts.

enitihas 10y ago

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.

jrs235 10y ago

https://leanpub.com/restful-api-design https://leanpub.com/restful-api-design

hbcondo714 10y ago

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

codegeek 10y ago

http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api http://www.vinaysahni.com/best-practices-for-a-pragmatic-res...

jgrandelli 10y ago
+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.
cyberferret 10y ago
+1 for Vinay's guide - super helpful while planning your API structure in the early days.

tengbretson 10y ago

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

ccleve 10y ago

Apigee's book is great: https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf https://pages.apigee.com/rs/apigee/images/api-design-ebook-2...

jbox 10y ago

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

esja 10y ago

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.com/en//pubs/archive/32713.pdf http://static.googleusercontent.com/media/research.google.co... https://www.youtube.com/watch?v=aAb7hSCtvGw https://www.youtube.com/watch?v=aAb7hSCtvGw

hinkley 10y ago
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,

smurfpandey 10y ago

https://github.com/interagent/http-api-design https://github.com/interagent/http-api-design

cesarb 10y ago

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 10y ago
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

solidgumby 10y ago

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

ccallebs 10y ago

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.

supergeek133 10y ago
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.
sd_sangit 10y ago
spot on my friend !!
cloudjacker 10y ago
lets look at how not to design an http API
- philgo20 10y ago
  Care to elaborate?
levbrie 10y ago
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.

deleted 10y ago

[deleted]

mchamati 10y ago

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

themihai 10y ago
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.

omgitstom 10y ago

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 10y ago
+ Etsy

divkakwani 10y ago

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

niftich 10y ago

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

danpalmer 10y ago

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 10y ago
Definitely, it is a great read.

Walkman 10y ago

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

johnwheeler 10y ago

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 10y ago
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.

andreasklinger 10y ago

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

pbreit 10y ago
Wouldn't most people disagree with: "not `/posts/343/comments` but `/comments?post_id=232`"?
- misterbwong 10y ago
  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.

dmreedy 10y ago

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

lnikkila 10y ago

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/

niftylettuce 10y ago
Amber rocks.
pbreit 10y ago
The amount of versioning that Stripe does makes nervous. Is that a good practice?
- deleted 10y ago
  [deleted]
- OJFord 10y ago
  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.
- Silhouette 10y ago
  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).

joeld42 10y ago

Casey Muratori - Designing and Evaluating Reusable Components https://mollyrocket.com/casey/stream_0028.html https://mollyrocket.com/casey/stream_0028.html

neves 10y ago

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.com/pt-BR//pubs/archive/32713.pdf http://static.googleusercontent.com/media/research.google.co...

philbo 10y ago
+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.

JimDabell 10y ago

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.

fzilla 10y ago
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.
MichaelGG 10y ago
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 10y ago
  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.

djuang1 10y ago

Check out http://raml.org/ http://raml.org/

b0sk 10y ago

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_revised.htm http://www.aristeia.com/Papers/IEEE_Software_JulAug_2004_rev...

mordocai 10y ago

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

mandeepj 10y ago

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/Guidelines.md https://github.com/Microsoft/api-guidelines/blob/master/Guid... 3. API via dll - 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 https://www.amazon.com/Framework-Design-Guidelines-Conventio...

mh8h 10y ago

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

rdsubhas 10y ago

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

pjmlp 10y ago

For C++ APIs, "API Design for C++" from Martin Reddy: http://www.apibook.com/blog/ http://www.apibook.com/blog/

idan 10y ago

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-Conventions-Development/dp/0321545613 https://www.amazon.co.uk/Framework-Design-Guidelines-Convent...

morenoh149 10y ago

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

darkfishboat 10y ago

Any good online courses?

gabriel 10y ago

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.

rudedogg 10y ago

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/

yareally 10y ago

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

abhip 10y ago

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-docs/ http://blog.parse.com/learn/engineering/designing-great-api-...

azhenley 10y ago

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.

aeijdenberg 10y ago

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.

caseysoftware 10y ago

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 10y ago
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.

edoceo 10y ago

Terrible API: BioTrackTHC Read their stuff for what to NOT do. Use it for real torture.

pedritter 10y ago

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

duncan_bayne 10y ago

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

Flenser 10y ago

https://github.com/SamHasler/Chrome-Bookmark-Exports/blob/master/rest-api.md#api-design https://github.com/SamHasler/Chrome-Bookmark-Exports/blob/ma...

erikb 10y ago

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.

danm07 10y ago

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.

cyberferret 10y ago

Aside from Vinay's guide that has already been mentioned - http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api http://www.vinaysahni.com/best-practices-for-a-pragmatic-res... There is also this Medium post: https://bradfults.com/the-best-api-documentation-b9e46400379a#.am4n12emj https://bradfults.com/the-best-api-documentation-b9e46400379...

rcpt 10y ago

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-macvean.pdf?ip=98.7.42.85&id=2851602&acc=OA&key=4D4702B0C3E38B35%2E4D4702B0C3E38B35%2E4D4702B0C3E38B35%2E3DF11CAF58636DA7&CFID=654192422&CFTOKEN=53191991&__acm__=1470883827_466b523ae56bf8bb522ce745f99241a0 http://delivery.acm.org/10.1145/2860000/2851602/ea849-macvea...

junto 10y ago

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.

wooptoo 10y ago

Web API design by Apigee - https://drive.google.com/open?id=0B8qU9uFznmLsdFBHS1I2c1ZLRkE https://drive.google.com/open?id=0B8qU9uFznmLsdFBHS1I2c1ZLRk... Restful service design - https://drive.google.com/open?id=0B8qU9uFznmLsUEZ3TEFMbDZQcUE https://drive.google.com/open?id=0B8qU9uFznmLsUEZ3TEFMbDZQcU... 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

AndrejXY 10y ago

I liked this one: REST API Design Rulebook, Designing Consistent RESTful Web Service Interfaces, by Mark Masse http://shop.oreilly.com/product/0636920021575.do http://shop.oreilly.com/product/0636920021575.do

sigjuice 10y ago

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