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.<p>Don't be overwhelmed by this though -- API design isn't an exact science. It's also very opinionated.<p>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.
When doing my last bigger API i read every recommendation. Still learned a lot.<p>Everyone has different recommendations - dont get discouraged by this.<p>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.<p>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:<p>- Autogenerate your docs with your tests<p>- Do versioning in URL (easier to route/cache/etc)<p>- Worry about caching (a lot)<p>- Personalized info only in isolated namespace, rest is fully cacheable<p>- Never embed personalized information (eg not `{ post: { user_has_commented: true } }`<p>- Never nest data (not `post: { author: { … } }` but reference only `post: {author_id: …}`)<p>- Embed referenced objects only by whitelist<p>- Never nest routes (not `/posts/343/comments` but `/comments?post_id=232`) filtering tends to become more complex<p>- Use public feedback tools (eg github issues) for your user questions/complains - so it can become searchable for people with similar problems<p>hth - happy to answer some of those in detail if useful<p>As said - highly subjective opinions - i am sure others might disagree w/ some of the points
I really liked Building Stripe’s API and it’s sequel, Move fast, don’t break your API:<p><a href="http://amberonrails.com/building-stripes-api/" rel="nofollow">http://amberonrails.com/building-stripes-api/</a><p><a href="http://amberonrails.com/move-fast-dont-break-your-api/" rel="nofollow">http://amberonrails.com/move-fast-dont-break-your-api/</a>
The Little Manual of API Design (Trolltech/Nokia):
<a href="http://people.mpi-inf.mpg.de/~jblanche/api-design.pdf" rel="nofollow">http://people.mpi-inf.mpg.de/~jblanche/api-design.pdf</a><p>How to Design a Good API and Why it Matters (Josh Bloch):
<a href="http://static.googleusercontent.com/media/research.google.com/en//pubs/archive/32713.pdf" rel="nofollow">http://static.googleusercontent.com/media/research.google.co...</a>
<a href="https://www.youtube.com/watch?v=aAb7hSCtvGw" rel="nofollow">https://www.youtube.com/watch?v=aAb7hSCtvGw</a>
Microsoft's REST API Guidelines are newly hosted on Github and were posted here last month with plenty of discussion:<p><a href="https://news.ycombinator.com/item?id=12122828" rel="nofollow">https://news.ycombinator.com/item?id=12122828</a>
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.<p>[1] <a href="http://shop.oreilly.com/product/9780596801694.do" rel="nofollow">http://shop.oreilly.com/product/9780596801694.do</a>
API could be in any form - be it a dll lib, wcf or rest so I am pasting a resource for each.<p>1. Restful API with WCF - <a href="https://msdn.microsoft.com/en-us/library/dd203052.aspx" rel="nofollow">https://msdn.microsoft.com/en-us/library/dd203052.aspx</a><p>2. Restful API using WebAPI - <a href="https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md" rel="nofollow">https://github.com/Microsoft/api-guidelines/blob/master/Guid...</a><p>3. API via dll - <a href="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" rel="nofollow">https://www.amazon.com/Framework-Design-Guidelines-Conventio...</a>
I thought <a href="https://apisyouwonthate.com/" rel="nofollow">https://apisyouwonthate.com/</a> was pretty good, assuming REST API.
This question is a little vague. My assumption is you mean a REST API.<p>This is a must watch and encapsulates good design and theory:
<a href="https://www.youtube.com/watch?v=hdSrT4yjS1g" rel="nofollow">https://www.youtube.com/watch?v=hdSrT4yjS1g</a><p>Good API design, if you are trying to learn from zero, comes from learning from good examples.<p>These are some of my favorites APIs by design<p>+ Stripe<p>+ Twilio<p>+ Slack<p>+ Stormpath (fd: I work here)<p>There is a lot of work that goes around the API design to make it a great API (examples, documentation, live samples, etc)
A good read for API design is "The Little Manual of API Design": <a href="http://www4.in.tum.de/~blanchet/api-design.pdf" rel="nofollow">http://www4.in.tum.de/~blanchet/api-design.pdf</a><p>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.<p>Many of the comments here take API to mean an HTTP exposed API (REST), but API stands for "Application Programming Interface"<p>It is much more generalized than APIs designed for HTTP consumption.
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.<p>The code examples almost become irrelevant because they make the patterns so clear.<p><a href="http://zguide.zeromq.org/page:all" rel="nofollow">http://zguide.zeromq.org/page:all</a>
I think it depends on what type of API you'd like to design.<p>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:<p><a href="http://restfulwebapis.org/" rel="nofollow">http://restfulwebapis.org/</a><p>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.
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.<p><a href="https://www.amazon.co.uk/Framework-Design-Guidelines-Conventions-Development/dp/0321545613" rel="nofollow">https://www.amazon.co.uk/Framework-Design-Guidelines-Convent...</a>
I found this SIGCHI paper from Google to be an interesting read. Abstract:<p>>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.<p><a href="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" rel="nofollow">http://delivery.acm.org/10.1145/2860000/2851602/ea849-macvea...</a>
Heroku's Interagent is a set of practical guidelines for building APIs based on their Platform API: <a href="https://github.com/interagent/http-api-design" rel="nofollow">https://github.com/interagent/http-api-design</a>
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.
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.<p>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
<a href="https://www.youtube.com/watch?v=aAb7hSCtvGw" rel="nofollow">https://www.youtube.com/watch?v=aAb7hSCtvGw</a><p>and the accompanying slides:
<a href="http://static.googleusercontent.com/media/research.google.com/pt-BR//pubs/archive/32713.pdf" rel="nofollow">http://static.googleusercontent.com/media/research.google.co...</a>
I always liked Rusty's list on making an API "hard to misuse" (and its followup):<p><a href="https://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html" rel="nofollow">https://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html</a><p><a href="https://ozlabs.org/~rusty/index.cgi/tech/2008-04-01.html" rel="nofollow">https://ozlabs.org/~rusty/index.cgi/tech/2008-04-01.html</a>
Aside from Vinay's guide that has already been mentioned - <a href="http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api" rel="nofollow">http://www.vinaysahni.com/best-practices-for-a-pragmatic-res...</a><p>There is also this Medium post: <a href="https://bradfults.com/the-best-api-documentation-b9e46400379a#.am4n12emj" rel="nofollow">https://bradfults.com/the-best-api-documentation-b9e46400379...</a>
I'm horribly biased as one of the co-authors, but check out: <a href="http://TheAPIDesignBook.com" rel="nofollow">http://TheAPIDesignBook.com</a><p>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.
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".<p>The docs have similar content: <a href="https://swift.org/documentation/api-design-guidelines/" rel="nofollow">https://swift.org/documentation/api-design-guidelines/</a>
Web API design by Apigee - <a href="https://drive.google.com/open?id=0B8qU9uFznmLsdFBHS1I2c1ZLRkE" rel="nofollow">https://drive.google.com/open?id=0B8qU9uFznmLsdFBHS1I2c1ZLRk...</a><p>Restful service design - <a href="https://drive.google.com/open?id=0B8qU9uFznmLsUEZ3TEFMbDZQcUE" rel="nofollow">https://drive.google.com/open?id=0B8qU9uFznmLsUEZ3TEFMbDZQcU...</a><p>Notes on RESTful APIs - <a href="http://wooptoo.com/blog/notes-on-restful-apis/" rel="nofollow">http://wooptoo.com/blog/notes-on-restful-apis/</a> - written by yours truly some years ago
This is my goto resource when the team starts bike-shedding on implementation details. <a href="http://jsonapi.org/" rel="nofollow">http://jsonapi.org/</a>
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<i></i>K U" to everybody who criticises your APIs, edit your APIs, rinse&repeat.<p>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<p>- Good summary of best practices for documentation: <a href="https://bocoup.com/weblog/documenting-your-api" rel="nofollow">https://bocoup.com/weblog/documenting-your-api</a><p>- Tips for good api doc design: <a href="http://blog.parse.com/learn/engineering/designing-great-api-docs/" rel="nofollow">http://blog.parse.com/learn/engineering/designing-great-api-...</a>
A cow helped me understand idempotency. :D <a href="http://www.restapitutorial.com/" rel="nofollow">http://www.restapitutorial.com/</a>
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.<p>A good starting point in this area is Steve Yegge's famous platform rant:<p><a href="https://plus.google.com/+RipRowan/posts/eVeouesvaVX" rel="nofollow">https://plus.google.com/+RipRowan/posts/eVeouesvaVX</a>
a bunch of API design guidelines flow from Scott Meyer's famous maxim "Make interfaces easy to use correctly and hard to use incorrectly."<p><a href="http://www.aristeia.com/Papers/IEEE_Software_JulAug_2004_revised.htm" rel="nofollow">http://www.aristeia.com/Papers/IEEE_Software_JulAug_2004_rev...</a>
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:<p><a href="https://www.infoq.com/articles/webber-rest-workflow" rel="nofollow">https://www.infoq.com/articles/webber-rest-workflow</a>
I found Apigee's API design eBook really useful:<p><a href="http://apigee.com/about/resources/ebooks/web-api-design" rel="nofollow">http://apigee.com/about/resources/ebooks/web-api-design</a><p>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.
Write code that is easy to delete, not easy to extend.
<a href="http://programmingisterrible.com/post/139222674273/write-code-that-is-easy-to-delete-not-easy-to" rel="nofollow">http://programmingisterrible.com/post/139222674273/write-cod...</a>
I asked myself this a couple of months back. Here's what I found <a href="http://harrymoreno.com/2016/03/31/API-design-link-roundup.html" rel="nofollow">http://harrymoreno.com/2016/03/31/API-design-link-roundup.ht...</a>
If you need programming APIs, and not necessarily REST, take a look at "Practical API Design, Confessions of a Java Framework Architect": <a href="http://www.apress.com/9781430209737" rel="nofollow">http://www.apress.com/9781430209737</a>
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.<p>*Like a freshman preaching Rand
Apigee's book is great:<p><a href="https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf" rel="nofollow">https://pages.apigee.com/rs/apigee/images/api-design-ebook-2...</a>
Have a look at Facebook's Graph API: <a href="https://developers.facebook.com/docs/graph-api" rel="nofollow">https://developers.facebook.com/docs/graph-api</a>
<a href="http://apiusability.org/" rel="nofollow">http://apiusability.org/</a><p>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 :/<p>C Interfaces and Implementations: Techniques for Creating Reusable Software By David R. Hanson
For C++ APIs, "API Design for C++" from Martin Reddy:<p><a href="http://www.apibook.com/blog/" rel="nofollow">http://www.apibook.com/blog/</a>
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.
Teach a Dog to REST: Some great REST API patterns distilled into a simple presentation <a href="http://www.slideshare.net/landlessness/teach-a-dog-to-rest" rel="nofollow">http://www.slideshare.net/landlessness/teach-a-dog-to-rest</a>