Restful API Naming Conventions guidelines
I believe that it is important before creating an API you have to think about its design first.
This should be the first step in creating a new API, rather than starting to write code and moving on with it,
I understand the enthusiasm of some programmers to start writing code and get things done, but through planning and design thinking, you will be able to get real benefits, which will make your tasks easier and better.
The real problem is that it is not easy to modify and fix the API after it is published,
You will have clients and systems that depend on what your API looks like,
So, if you make mistakes in the way the API is designed, you will inevitably be in an unenviable situation,
I know that some solutions are easy to solve by adding new endpoints, but this is not the best way,
We really need to understand the API requirements well before we start building it, don’t just take the standard form of what you’ve seen in other companies .
When we think about REST APIs, I want you to think about the different pieces of it before we decide what to put in each of those parts.
What’s important to note is you’re designing each part of a REST API, not just the URL. Of course, the starting point is that URI, what that path is on some web server.
But we’ve also got the verb, this is the indicator of what your intention to do at that URI is, and then HTTP and headers whether your clients are going to need to use headers or need to be able to read headers, and then the request body if any.
When we look at the response you’re sending back, you also have that similar set of parts of the API. You have the status code, what sort of response is going to be sent back to say that it succeeded or failed or how it’s going to fail? You have headers that may be sent back to the client to indicate things and then the response body, the thing they asked for.
Let’s start the discussion with URIs and naming conventions and Best Practices
In REST, URIs are just paths to resources so when you have your server, there is an API, it’s whatever path follows your server name to indicate how to get to some object on that server.
Part of that URI that we don’t think about when we’re designing the APIs is often the query strings. So, the things that can be added to the end of the URIs to indicate things. Now query strings should always be optional when you think about them logically. And so, they’re often used for things like formatting and sorting and searching.
Here are some guidelines for API Naming Conventions
1. Use Nouns to represent resources / Not Verbs
So, as you’re designing the API, I want you to think about the names. Nouns are good and verbs are bad. Here are some
bad examples
̶h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶u̶s̶e̶r̶/̶C̶r̶e̶a̶t̶e̶U̶s̶e̶r̶
̶ ̶h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶u̶s̶e̶r̶/̶G̶e̶t̶U̶s̶e̶r̶/̶{̶U̶s̶e̶r̶I̶d̶}̶
̶ ̶h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶u̶s̶e̶r̶/̶u̶p̶d̶a̶t̶e̶U̶s̶e̶r̶/̶{̶U̶s̶e̶r̶I̶d̶}̶
̶ ̶h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶u̶s̶e̶r̶/̶d̶e̶l̶e̶t̶e̶U̶s̶e̶r̶/̶{̶U̶s̶e̶r̶I̶d̶}̶
in the start when I was building APIs, it was very easy for me to think of these as just RPC endpoints. So, get the users, check something, update the user, and it all makes sense. But in REST APIs, what we’ll actually look at is that we prefer names like
http://api.example.com/v1/users
http://api.example.com/v1/users/id
What are resources?
we can think about it as just a collection of those nouns, like People in an organization, invoices that exist in an system, it’s like entity
2. Use Pluralized Nouns for resources
Do not use the singular form, use the plural form
Here are some bad examples
̶h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶u̶s̶e̶r̶/̶1̶
̶h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶d̶e̶p̶a̶r̶t̶m̶e̶n̶t̶ ̶
Use plural with resources.
http://api.example.com/v1/users/1
http://api.example.com/v1/departments
3.Use hyphens (-) to improve the readability of URIs
Do not use camel case or underscores to separate words in URLs
if you have a long word use (-) it’s better than other ways
bad examples
̶h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶u̶s̶e̶r̶m̶a̶n̶g̶m̶e̶n̶t̶
̶h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶u̶s̶e̶r̶M̶a̶n̶g̶m̶e̶n̶t̶
good examples
http://api.example.com/v1/user-mangment
Use forward slashes (/) for hierarchy
Forward slashes are used to show the hierarchy between individual resources and collections.
good examples
http://api.example.com/v1/users/Id/departments
4. Use quire string for non-resource properties
While designing your URI, you also want to think about how you’re going to use query strings. So these are typically used for non-resource properties.
So it could be in the way you want to use query strings to sort, to the page, to specify a format, etc.
This really comes down to not requiring any of these, but allowing developers to have more control over how you’re going to get this information in the way of, you know, getting page results versus sorted results, etc.,
so that you can allow them to do things that aren’t necessarily about specifying how the resource is going to be constituted, but how the resource is returned.
http://api.example.com/v1/users?page=10
5. Don’t use file extensions with URLs
bad examples
h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶u̶s̶e̶r̶s̶.̶j̶s̶o̶n̶
h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶u̶s̶e̶r̶s̶.̶x̶m̶l̶
good examples
http://api.example.com/v1/users
http://api.example.com/v1/departments
6. Filter, and sorting orders, are not recourse
Don’t deal with filter, sorting, order …etc. as a resource
This means that the filter, sorting, order …etc. shouldn’t be sent as a parameter, but rather it should be sent in a Query string.
bad examples
h̶t̶t̶p̶:̶/̶/̶a̶p̶i̶.̶e̶x̶a̶m̶p̶l̶e̶.̶c̶o̶m̶/̶v̶1̶/̶u̶s̶e̶r̶s̶/̶o̶r̶d̶e̶r̶B̶y̶/̶n̶a̶m̶e̶
good examples
http://api.example.com/v1/users?orderBy=name
7. Use the HTTP verb to indicate what you want to do on a specific request.
let’s talk about what each of these verbs should do.
· GET
The GET method requests a representation of the specified resource. Requests using GET should only retrieve data,
So GET wants to retrieve a resource, whether that’s a collection of resources, or it might be an individual site.
· HEAD
The HEAD method asks for a response identical to a GET request, but without the response body.
· POST
The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server. So, POST is adding a new resource, or you could think about it as creating a resource.
· PUT
The PUT method replaces all current representations of the target resource with the request payload.
PUT is updating an existing resource, so taking a resource with information that might have been changed and updating it to reflect new data.
· PATCH
The PATCH method applies partial modifications to a resource.
PATCH is very similar to PUT except it’s updating a resource with certain data changes. So instead of using PUT to send a whole object. you might just send some partial object.
· DELETE
The DELETE method deletes the specified resource.
· CONNECT
The CONNECT method establishes a tunnel to the server identified by the target resource.
· OPTIONS
The OPTIONS method describes the communication options for the target resource.
· TRACE
The TRACE method performs a message loop-back test along the path to the target resource.
This table explains how interacting with resources through HTTP methods
