Improve your API design by following this simple step — Part 2
My department went through a transition from 5 to 25 software engineers. Number of teams grew as more and more developers joined the company. This brought many challenges, including building consistent REST API across different teams. We’ve put up together a REST Resource Naming Guide to remove confusion and uncertainty within the team.
REST Resource Naming Guide
Ideally, all design decisions should be documented and be available as general knowledge within the company. In my previous article, we’ve come up with a good name for GET endpoint. Also we’ve documented our decision process. We called it REST Resource Naming Guide. So far it consists of two rules:
1. All REST endpoints should have slash in the end
2. All REST endpoints should have singular form of nouns in the name
I suggest extending this guide even further over the course of this article.
Example
Let’s look at the Bookstore web application from the previous article. We need to be able to create books via REST API. Thus we want to define a good name for the POST endpoint for that. We will brainstorm all possible names for the POST endpoint and then we refine this list.
Brainstorm all possible names for a POST endpoint
After brainstorming all possible names for our POST endpoint, I’ve come up with:
POST: /books/add
POST: /Books/add
POST: /Book/
POST: /Book
POST: /book/add
POST: /book/create/
POST: /books/create/
POST: /books
POST: /books/
POST: /book/post
POST: /books/post/
POST: /book
POST: /book/
POST: /addBook
POST: /createBook/Let’s refine this list now.
Filter out the bad names using our Naming Guide
To filter out bad names from the list above — we apply two rules from our REST Resource Naming Guide. Here is what we’re left with:
POST: /Book/
POST: /book/As we can see we need to pick the casing. Let’s imagine that we want only lower case in our endpoints. We are going to put a new rule to the Guide to document this decision.
3. All REST endpoints should be lowercase
After adding this rule — we can choose the winner.
POST: /book/payload: { name: "Harry Potter", author: "Rowling" }
PATCH endpoint
We can easily come up with the PATCH endpoint with our Naming Guide:
POST: /book/payload: { author: "J.K. Rowling" }// author is a property of the book
Payload
In the payload of a PATCH request for the book we want to specify properties that are present on the book, like name and author. It would be confusing to put other variables into the payload.
POST: /book/payload: { pageNumbersToDelete: [1, 2, 3] }// pageNumbersToDelete is not a property of the book
Conclusion
Documenting design decisions can be a very good practice. It can help other developers to choose the correct naming and remove uncertainty when designing REST API as your team grows. Documentation can take many shapes. One of the shapes we discussed in this article — REST Resource Naming Guide.
Other REST articles you may like
