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:
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.
This MDN doc covers some of the complexity:
And here is when browsers added support for CORS:
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.
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...  seems to confirm this.
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.
This page describes some the principles behind the design of the API.
Design and designers, vast majority of them are chasing aesthetics and trends. Just go on Behance to see it for yourself.
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."
All designers know that.
Agree 100%, but good APIs aren't just a raw interface to a snapshot of how a system happens to be implemented at the time the API was defined.
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.
It goes beyond "what is rest" and real life UX of apis
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.
Chapter introducing REST: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...
I went ahead and gave it a read but didn't dig in deeply to get all the context. As such, I feel like some things must have gone right over my head.
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.
This is short one based on RedHat VM engineer experience:
Manning has a solid books on topic:
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.
My reference when I'm designing a REST API.
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.
You can read it in an hour or two. It cover a lot of things that you should consider
This has an interesting generic discussion of API design which is technology agnostic.
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 internal software, you use whatever works.
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.
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).
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.
- 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.
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).
It even spends the first few chapters talking about API design in general (not just for REST) with really great, intuitive examples.
Another excellent reference is the "The Linux Programming Interface" book by Michael Kerrisk that documents most of the API available under Linux .
It is everything you need to know and thinks about the angle of the people who need to consume your API. Quick read too.
It's targeted at developing .NET frameworks with a broad audience so some of the guidelines aren't appropriate for internal APIs or applications.
REST API guidelines from Microsoft
But know that they're all wrong. Some fatally.
The best you can do, ever, is to be consistent. So pick a style and stick to it. Honor the principle of least astonishment.