RESTful API Design: nouns are good, verbs are bad
I have defined "pragmatic REST" as looking at API design from the developer point of view. Now let's get into specific design practices we've seen work well.
The #1 principle in pragmatic RESTful design is: keep simple things simple.
Keep your base URL simple and intuitive
The base URL is the most important design affordance of your API. A simple and intuitive base URL design will make using your API easy.
A design affordance is a design element that communicates how something should be used without requiring documentation. A door handle's design should communicate whether you pull or push. But here's an example of a conflict between design affordance and documentation - not an intuitive interface!
My key litmus test for simple API design and pragmatic REST is: only 2 base URLs per resource
Let's model an API around a simple object or resource (dogs) and create a RESTful API that interacts with dogs.
The first base URL is for collections; the second is for a specific element in the collection.
Boiling it down to this level will also force the verbs out of your base URLs.
Keep verbs out of your base URLs
Many RESTful APIs start by using a method-driven approach to URL design. These method-based URLs sometimes contain verbs - sometimes at the beginning, sometimes at the end.
For any resource that you model, like our dog, you can never consider one object in isolation. Rather, there are always related and interacting resources to account for - like owners, veterinarians, leashes, food, squirrels, and so on.
Think about the method calls required to address all the objects in the dogs world. The URLs for our resource might end up looking something like this:
It's a slippery slope - soon you have a huge list of URLs and no consistent pattern making it difficult for developers to learn how to use your APIs.
Use HTTP verbs to operate on the collections and elements
For our dog resources, we have two base URLs that use nouns as labels, and we can operate on them with HTTP verbs. Our HTTP verbs are POST, GET, PUT, and DELETE. (I think of them as mapping to the old metaphor of CRUD (Create-Read-Update-Delete).)
With our two resources (
/dogs/1234) and the four HTTP verbs, we have a rich set of capability that's intuitive to the developer. Here is a chart that shows what I mean for our dogs.
The point is that a developer probably doesn't need the chart to grok how the API behaves. They can experiment with and learn the API without having to dig into the documentation.
In summary: Use 2 base URLs per resource. In your URLs - nouns are good; verbs are bad.