REST API Best Practice for Developers.

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.

1. 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);

1. 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.

1. 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

1. 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.

1. 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!