REST API Development — Best Practices

Photo by Cookie the Pom on Unsplash

If you are a web developer then you need to write a lot of endpoints throughout your career. With modern frameworks writing API endpoints are easy. Because of that, we can find many good developers who are good at writing API endpoints. But what makes you an exceptional developer good at writing APIs are small qualities/practices which will have a great impact on the consumers of the APIs. Below are some of the best qualities/practices that I found during my career as a web developer which may help you to move from a good developer to an exceptional developer.

Designing

When creating API endpoints use nouns, not verbs.

Always make sure to create API endpoints using a noun. If not, the API will contain many redundant actions and this will lead to maintaining mess when the number of API endpoints increases. The below example illustrates the best practice when naming API endpoints

Imagine creating an API to get, create, update and delete companies. The bad practice would be to create endpoints as verbs as follow.

• /getCompany
• /getAllCompanies
• /addCompany
• /updateCompany
• /deleteCompany

The best practice would be to use nouns rather than verbs and use HTTP methods to illustrate the verb. Below would be the same endpoints according to best practice.

• GET /companies
• POST /companies
• PUT /companies
• DELETE /companies

Resource names should be plural

Resource names should be plural in order for better understanding for humans. For instance, consider the following two endpoints.

• GET /company
• GET /company/:id

At first glance, the consumers will have a doubt of whether the first endpoint is returning a single company or multiple companies. Only when we look at the second endpoint we identify that ok, the second endpoint is giving a single company, so the first endpoint will provide multiple companies. To avoid this confusion for our consumers we can name our…