REST API Best Practice for Developers.
Tags: java, programming, javascript
Published: 2022-10-05 22:53:15



![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/skdxtkba9zdq3ovpio8i.jpg)

What’s up, guys? Thank you for tuning in. I hope you will enjoy this that you are about to read. We all know that **Facebook**, **GitHub**, **Google**, **Flutterwave**, **Cowrywise**, **Netflix**, and a few other tech monsters have given a red carpet welcome to developers to exploit their data using APIs. 
Today, it is becoming a trend for innovative tech platforms to elevate their platform with beautifully composed REST APIs.

The critical point here is perfectly designed REST APIs. If the REST API isn’t designed flawlessly, it can create problems for developers instead of easing the user experience. Thus, it is highly critical to use the commonly followed conventions of API design to serve the best solution to your clients or developers.

_Best practice_

1. **REST API Must Accept And Respond With JSON**

It is a common practice that APIs should accept JSON requests as the payload and also send responses back. JSON is an open and standardized format for data transfer. It is derived from JavaScript in a way to encode and decode JSON via the Fetch API or another HTTP client. Moreover, server-side technologies have libraries that can decode JSON without any hassle. I will show you an example of an API where JSON accepts payloads.

```
{
    "username" : "zipDemon",
    "phoneNumber" : "09152624528",
    "languageCode" : "en"
}
```

Therefore Use JSON as the Format for Sending and Receiving Data.

2. **Always Have Error Status Codes**

It is very compulsory for developers to use status codes in their REST API design. With the status codes, developers can instantly identify the issue, which reduces the time of writing parsers to address all the different types of errors. There’s a status code for everything from finding out the cause of a denied session to locating the missing resource. This will help your users to know what is going on whether the request is successful if it fails, or something else. For example

```
if (userService.existByEmail(user.getEmail())){
    throw new BlogException("User with that email already exist.");
}
ResponseDetails responseDetails = new ResponseDetails("successfully", HttpStatus.OK.toString());
return ResponseEntity.**status(200)**.body(responseDetails);

```

3. **Name Collections with Plural Nouns**

When you have to develop the collection in REST API, just go with plural nouns. It makes it easier for humans to understand the meaning of the collection without actually opening it. 
If you have an endpoint like _https://codegun.com/comment/198_, it might be okay for deleting a post with a **DELETE** request or updating a post with a **PUT** or **PATCH** request, but it doesn’t tell the user that there could be some other posts in the collection. The example doesn’t clearly show whether there is more than one comment in the system or not. For a human reader, it might be challenging to understand, as well. This is why your collections should use **>plural nouns**. So, instead of _https://codegun.com/comment/198_, it should be _https://codegun.com/comments/198_.

4. **Don’t Use Verbs In URLs**

When you’re designing a REST API, you should not use verbs in the endpoint paths. The endpoints should use nouns, signifying what each of them does. This is because HTTP methods such as **GET**, **POST**, **PUT**, **PATCH**, and **DELETE** are already in verb form for performing basic **CRUD** (Create, Read, Update, Delete) operations. There are also others such as **COPY**, **PURGE**, **LINK**, **UNLINK**, and so on.

So, for example, an endpoint should not look like this _https://codegun.com/getUserComment/20_. Instead, it should be something like this: _https://codegun.com/comments/20_

5. **Provide Accurate API Documentation**

When you make a REST API, you need to help clients (consumers) learn and figure out how to use it correctly. The best way to do this is by providing good documentation for the API.

The documentation should contain:

- Relevant endpoints of the API

- Example requests of the endpoints

- Implementation in several programming languages

- messages listed for different errors with their status codes

One of the most common tools you can use for API documentation is **Postman**. 

> It is a simple principle the faster developers understand your API, the faster they start using it.
 Your API documentation must be compiled with precision.

6. **Use Filtering, Sorting, and Pagination to Retrieve the Data Requested**

Sometimes, an API’s database can get incredibly large. If this happens, retrieving data from such a database could be very slow.

**Filtering**, **sorting**, and **pagination** are all actions that can be performed on the collection of a REST API. This lets it only retrieve, sort, and arrange the necessary data into pages so the server doesn’t get too occupied with requests.

An example of a filtered endpoint is the one below:
**https://codegun/posts?tags=java**. This endpoint will fetch any post that has a tag of java.

It is important to put these best practices and conventions into practice so you can build highly functional applications that work well, are secure, and ultimately make the lives of your API consumers easier.

Thank you for reading. **zip it now**!