Naming your REST endpoints
How to name your REST endpoint? How does your endpoint look? Are there any guidelines or best practices? How to name your endpoints?
A short introduction
We often use APIs to implement CRUD operations, or most APIs start like this, but all of them evolve over time.
CRUD is an acronym that stands for Create, Read, Update, Delete. And these are all the operations that you can apply to a specific resource.
Let’s take childish example, and say you need to manage pets for a veterinary cabinet and you are interested in cats:
/api/getAllCats– wouldn’t /api/cats be easier to remember?/api/newCat – how about /api/catsand use POST as HTTP Verb?/api/getBlackCats– why should you have a different endpoint? /api/cats?color=blackwill have the same path, but the parameter value will change an get you a lot of flexibility/api/getCatsOwners– how about /api/cats/{id}/owners– this way you will know exactly to which cat you are reffering. The one with the {id} in the URL path./api/getHungerLevel– hunger level of…? cat? which cat? maybe is youru hunger level?
If you look at the endpoints, are very hard to remember, and once you add more operations, it will be even harder to remember and harder to manage. Plus, you have no reason to include get{something} in the endpoint or have tons of endpoints. The HTTP verb will be the one that tells what operation you are doing. Either is a GET, a POST or something else. KISS, as in code, also applies here. And more than that, we need to keep in mind that we need to leverage the underlying protocol as much as we can.
In my opinion, an endpoint in a REST API should be self-explanatory. Just by looking at the URL, you( and the server) should be able to tell what is the resource it handles without needing a manual.
One ot the things REST is trying to do, is to remove the uglyness we all dealt with in SOAP. SOAP exposed a set of operations in a WSDL file, and to ‘call’ those operations we made a single type of call(POST or GET). REST is trying to get rid of that paradigm and get us closer to the underlying protocol.
Luckily, if you are nostalgic(or not) we have tools like Swagger and the Open API standard to help us with the documentation, but even so, and URL should express intent in the ‘eyes’ of the consumer.
COOL URI’s don’t change.
Let’s look at the 2 endpoints that you will need in a REST API.
An endpoint for the collection
/api/cats
This will allow you 2 operations:
- retrieve the collection by HTTP GET (a read)
- Create a new resource by using HTTP POST (a create)
An endpoint for a specific item
/api/pets/{id}
This will allow you 4 operations:
- retrieve the item by using HTTP GET(a read)
- update an existing resource by using HTTP PUT(an update) or HTTP PATCH
- delete and existing resource by using HTTP DELETE(a delete)
Related/hierarchical resources
Any hierarchical resource can be represented further in the URL path, but the convention remains, and applies down in the hierarchy.
Let’s take the example of wanting to represent the owners of a specific cat:
/api/cats/{id}/owners
Looking at this URL we realize that in the cats collection, we are interested in the specific {id} of the cats, and from this specific cat, we want the owners collection.
When we obtain the list of owners, we might be interest to obtain a specific one, and we can take another step : /api/cats/{id}/owners/{ownerid}
You are not forced to model your data and store it in the database according to the endpoints, or the other way a round. Remember, in REST, you work with representations of resources, and those representations are handled by you. At the server level, for more decoupling and simplicity, you should use DTOs to transform or aggregate data.
Takeaways
- Name your endpoints in such a way to have meaning for the business and your consumers
- You don’t need a different endpoint to represent a new operation. You can give meaning to your request by using the right HTTP verb
- You can use GET, POST to the same endpoint /api/cats : the end result will be different.
- you need two endpoints to represent major operations on a resource
- Variations of specific resources can be represented as parameters in the query string, not different endpoints.
In conclusion, it is up to you how you shape your endpoints. There is no constraint in this. As long as it makes sense for the business, expresses the intent, and is specific enough.
The meaning for each request/response should be added by using the right HTTP Verbs, headers and status codes.
