Not a book, but the best recorded talk ever given about API design is (IMO) by Joshua Bloch, in a 2007 tech talk at Google. "How to Design a Good API and Why It Matters".
He was one of the creators of the Java Collections API and the Java Executor Framework, two of the most durable and most widely-copied APIs ever. That may not seem relevant for an HTTP/REST API, but it is. The design principles are timeless. Here's that reference:
When I had to design a widely-used "HTTP/RESTful" API a few years back, I wrote a summary of the design principles here. It also includes a reference to an old O'Reilly book on the topic, which I summarized:
I really cannot agree with the "just use GET" suggestion. GET must not be used for actions that modify the data server-side. Also, POST and PUT means some action is or is not idempotent.
Using different methods than GET is easy in the browser (easier than JSON-P) and avoids a huge class of problems that come with abusing GET.
Yes, honestly this was written at a time when browsers (specifically, the XHR API) did not support non-GET requests reliably at all (e.g. pre-CORS), so there was no other option. (And once you publish an API, it's hard to change.) You're right that today there is better support for POST/PUT, although there might still be some issues lurking in the corners.
In a cross-domain context, when you are expecting the browser to make its XHR for JSON data via JavaScript to a third-party API. Think about making a call to the Flickr.com HTTP API from your own WordPress myblog.com domain. In that context, the XHRs didn't support POST/PUT. Remember, even the fetch() API is pretty recent. POST-based forms are irrelevant for API usage.
I dimly recall a pre-form web, but it could easily be they just took over a little-used Berners-Lee verb. (For instance, PUT support was atrocious for a while.)
This is not about pre-form web. It's about pre-CORS web. Which is pretty recent web. CORS was "widely & properly" supported by "recently released" browsers around 2012-2013. Of course it's only as of very recently that you could safely assume 2010-2013 browser versions were completely out of circulation.
My bad; hadn't parent'ed enough, and the "using different methods than GET" clarification would not have been anachronistic even in the previous century.
PUT can still be weird. For example, PHP doesn't process multipart/form-data if it's a PUT instead of a POST, I'm working on an API in Laravel and for methods that need to PUT a file I have to use Laravel's _method spoofing.
Agreed about the idempotency concern. Safari for example will sometimes make past GET requests while making a current GET request, so you can get oopsied if you put a non-idempotent request in a GET.
On the other hand, if multi submitting causes bad behavior, a failsafe should probably be baked in to the endpoint logic itself rather than relying on POST not being abused.
I got to take a course on API Design with Joshua Bloch and Charlie Garrod (CMU's 17-480) in the spring. While I don't think the course content is available online, there's a good amount of tactical advice that goes with the talk [1]. The most memorable things to me were an emphasis on user testing to validate your design - we would draft APIs and then interview people and make them try to write code with them; and being willing to go back to the drawing board to change things if necessary. I think these are common ideas in (visual) user interface design, but for some reason are overlooked in coding.
There was an anecdote about how the creator of the Makefile (Stuart Feldman) originally hacked together the implementation so that tabs were required for each command (rather than spaces), and didn't want to change it because dozens of people were already relying on that behavior at this point... [2] seems to confirm this.
Really need to couch in terms of "value" to the individuals and org - point to bugs/regressions caused by loose interfaces, copy pasted code, able to use cool tools if you follow REST, JSON-API, GraphQL, etc.
Most folks seem totally unpersuaded by "maybe one day 3d parties will use this API!" hypotheticals.
I agree with the sibling comment that showing concrete failures that were caused by or contributed to by poor API design is effective.
If it's a public (customer-facing) API, perhaps you can compare your version to a competitor's: to achieve the same task, what needs to be done?
Internally... I haven't had a lot of luck here. Push for it in code/design reviews and sneak a refactor into your PRs? One thing that helps is to have ready examples, so you can say "Hey, I think we need a higher level abstraction here or else we'll be copy-pasting around the same 12 calls every time we want to X, just like we already do with Y API." and your teammates hopefully recognize that pain.
I dunno how much I'd trust a Google speech about api design. Few of their API follow the same rules and most are horrendous to work with. It's the wildwest over there.
Don Norman’s “The Design of Everyday Things” (https://en.m.wikipedia.org/wiki/The_Design_of_Everyday_Thing...). Yes, API design has its own gotchas and specific practices—but some of the best (and worst) APIs I’ve ever interacted with were good (or bad) for the same reasons any kind of design can be good ( or bad): affordances, feedback, coherent conceptual models, and so on.
Yep, I second this. Don Norman really and truly understood the user in the deepest way. It’s hard to find people like him who put their entire consciousness in the shoes of the user, simulate what the user goes through when interacting with the world and provide insights about how, we the designers, on the opposite aisle think about design as not some aesthetic shit but as a tool to solve problems.
Design and designers, vast majority of them are chasing aesthetics and trends. Just go on Behance to see it for yourself.
That's about as accurate a judgment on designers as calling programmers "code monkeys."
Follow a couple designers on Twitter for a few weeks and you're almost guaranteed to see someone quote Steve Jobs saying "Design is not just what it looks like and feels like. Design is how it works."
To be fair, most programmers are code monkeys. But that's true for most people in any profession. It's not a fair comparison to compare the average worker to workers of excellence.
I came to say exactly the same thing! An API should guide a user to form a mental model that is consistent with the actual inner workings to avoid frustration and making errors (the importance of this cannot be overstated for critical functionality like authentication/authorization).
Isn't that the opposite of the lesson to learn? Design should be sending the correct outward signals and function the way users will expect. Users should not need to understand the inner workings.
Like it or not, users develop a mental model. The fridge example in the book shows how hiding too much of the inner workings can make your system less intuitive to use.
It doesn't mean to unnecessarily expose implementation details, but I take it to be the other way around: implement things in a way that things work consistently without having to know the nuts and bolts.
The lesson from the book is that users will always form a mental model of how the machine works. That's fine even if it's wrong, as long as it works. But when things don't work and users have faulty assumptions about what may be the problem, it becomes hell.
I’d highly recommend reading Roy Fielding’s dissertation paper where he introduced REST.
For anyone who hasn’t read it, it will fundamentally change how you think about REST and APIs for network services, and you’ll create much better APIs armed with that deeper understanding.
REST is fundamentally about how do to useful communication between networked services. I'd recommend reading the paper for anyone doing anything related to that. I happen to use GraphQL at work, but that doesn't stop me from learning a lot from the paper.
Not a book, but MS REST API Guidelines are pretty good although they don't cover funky important details like how to properly do REST operations/actions.
I would suggest having a close look at the OpenAPI specification as a way to bound and constrain your REST API design: https://swagger.io/specification/
Once you start thinking in terms of requests, responses, parameters, schemas etc the rest should easily fall into place! You also get the benefit of having a machine readable definition of your API if you write your design with the spec.
It's not about designing APIs, it's about designing your software to reflect the reality you're encoding into your software. It's a book of first principles that you can apply to any software you design.
I hadn't heard of Increment before. They have some very interesting articles! I like how they group a number of articles from different authors on a related topic. Thanks for sharing.
The most influential technical book I have read over the past 10 years for sure.
The author guides the reader though the process of managing complexity with some intriguing concepts such as "Define errors out of existence" and "Deep modules".
I definitely recommend it.
I found JSON:API to be a great starting point, especially for small teams that want to get started right away. You can either adopt it or use it as a guideline for all the topics you need to consider.
I was looking for this specific title in the suggestions, as I got this recommended myself a few years back. If we have the same little manual in mind, it's by Jasmin Blanchette. I can't say anything about the other 19.
Do people still design rest-ful APIs? I often find I end up needing to do RPC-like things that make the API end up as a weird hybrid. I'm on the verge of abandoning the idea of trying to be rest-ful at all, so it's less incohesive.
One of the things we insisted on building our internal ML platform was that every functionality should be accessible through an API.
This is scar tissue from our many past projects that delivered value to clients, but could not easily be leveraged as building blocks to do something else, especially when you have different stacks.
So now, we always strive to make everything that the platform can do possible through an API call, from scheduling a training job, to deploying a model, or invoking functionality from dynamically loaded applications, which also expose their API.
"Anything you can do with point and click should be accessible with an API call." guides us.
For the public API of a major service? Yes, REST is definitely still around. REST or at least REST-like APIs are still almost universal in my experience.
Surprising question, as I think REST is probably the leading paradigm for public APIs. At least in terms of what people call their API. What RESTful actually is varies from person to person.
Honestly, prefer GraphQL -- it's more like designing a schema which you may already be doing in your database anyway. The client decides which data in what shape it fetches.
If you're designing an internal API to power a rich client app, yes. If you're designing an API for developers to interface with you SaaS, plain old HTTP is a better choice, even if it's only RESTful in a hand wavy sense.
I don't have any book recommendations to make since API design is more art than science. As such I'd recommend that you beta test the API (route names, payloads, etc) with a few potential users to gauge durability and the ease with which users can intuit. The last thing you want is to release new version quickly or to require users to always refer to your documentation.
Some of these problems can be solved with an SDK (highly recommend, as it can greatly improve developer experience especially in a modern text editor or IDE) or switching to GraphQL (not without its own problems).
I just read through a good chunk of this, hoping it'd be a good resource.
There's a lot of good stuff in here:
- Higher level than a spec, but still detailed.
- He outlines the anatomy of an HTTP request and gives examples.
- Lots of good suggestions of conventions and rules of thumb, e.g. for URL structure and naming.
- Good demonstration of why using fitting HTTP verbs is important. Explains idempotent and safe.
On the flip side, his ethos isn't the best at points, he presents some subjective takes as fact, and even includes some plain errors against the specification.
For example:
- JSON keys should be snake cased, or camelCased "if you're one of _those_ people". (I'm a snake case guy, but really?)
- Return a 400 if there are any problems with the request. (400 explicitly means request body can't be parsed, e.g. syntax error in your JSON. The spec isn't perfect, but 422 is often more fitting if the consumer input didn't pass validation. Either way 400 clearly violates the spec.)
- He misses the nuance of what PUT is in the spec. You're saying "store this resource at this URL". Not technically update. Although in practice it's usually update, and I'm sure this point will be viewed as pedantic by many.
Overall a decent resource, but take it with a grain of salt.
I read this book for a public API project I was working on. At the time I had done several Rest APIs but for internal use. When it came time for a public API, you really need to up your game. A public API says a lot about a company. It's essentially marketing and sales plus a way to interact with your company programmatically. This book covers all your basics of Rest API design.
Another topic to read up on intent API design (intent resources). If you stick to nouns as your resources, you will encounter issues with naming APIs that have several steps or are really executions of business processes/procedures. With intent resources, you can continue to use the noun paradigm for naming your APIs but still be able to have complicated APIs (more than just simple CRUD).
Please check "The C Interfaces and Implementations" book by David Hanson [1]. Someone has implemented the concept using his library that you can check and use [2].
Another excellent reference is the "The Linux Programming Interface" book by Michael Kerrisk that documents most of the API available under Linux [3].
Great recommendations! For another perspective, I'd add O'Reilly's "Continuous API Management" with some chapters around designing APIs as products and suggestions around how to implement a lifecycle.
Also, strictly for design I'd also do what was suggested here and check API design guidelines from several sources. I like the Adidas one.
for REST APIs, https://apisyouwonthate.com/books/build-apis-you-wont-hate book is my recommendation if you haven't read it already. I read it as a beginner, so it was kind of an eye opener for me on why we should do things a certain way when it comes to API.
He was one of the creators of the Java Collections API and the Java Executor Framework, two of the most durable and most widely-copied APIs ever. That may not seem relevant for an HTTP/REST API, but it is. The design principles are timeless. Here's that reference:
https://twitter.com/amontalenti/status/1260030567501840386?s...
When I had to design a widely-used "HTTP/RESTful" API a few years back, I wrote a summary of the design principles here. It also includes a reference to an old O'Reilly book on the topic, which I summarized:
https://www.parse.ly/help/api/restful-apis