REST API Best Practices

Hello, Habr! I present to your attention the translation of the article " .REST API Best Practices " By Krishna Srinivasan.
 
 
REST is becoming a common approach to presenting services to the outside world. The reason for its popularity lies in its simplicity, ease of use, access via HTTP and others. There is a misconception that all data available through the network is considered REST, but it is not. In this article, I'm going to explain to you some of the best practices that you should always remember when implementing your own REST application. I would like to hear your experience in REST applications, so if you know the best practices that are not mentioned in this article, please share with us in the comments.
 
 
Disclamer : all the best practies are based on my personal experience. If you have a different opinion, do not hesitate to send it to me by email, and we will discuss it.
 
 
Here is a list of best practices that will be discussed in this article:
 
 
1. The endpoints in the URL are a noun, not the verb
 
2. The plural number is
 
3. Documentation
 
4. The version of your application is
 
5. Pagination
 
6. Using SSL
 
7. HTTP methods
 
8. Effective use of HTTP response codes
 
REST web services , which provide information on Indian farmers. The service should also implement functionality that provides information such as farmer's income, crop names, farm addresses and other information pertaining to each farmer. Each farmer has a unique id.
 
 
In the same way, services that provide information about cultures and which farmer owns them should be implemented.
 
 
Best Practice:
 
 
We have a single endpoint, which is responsible for all actions. The example below shows only one endpoint /farmers for all operations such as adding, updating, or deleting. Basic implementations have different HTTP methods that are correctly routed for different operations.
 
 
• /farmers
 
• /crops
 
 
Not recommended:
 
 
Try to avoid using verbs. It is recommended to represent operations inside such formats as JSON, XML, RAML or use HTTP methods. Do not use the following symbols:
 
 
• /getFarmers
 
• /updateFarmers
 
• /deleteFarmers
 
• /getCrops
 
• /updateCrops
 
• /deleteCrops
 
 

2. The plural number


 
Use the plural for the name of your REST services. This is another hot topic for discussions among REST designers - the choice between single or multiple forms of nouns to designate services.
 
 
Best Practice:
 
 
• /farmers
 
• /farmers /{farmer_id}
 
• /crops
 
• /crops /{crop_id}
 
 
Not recommended:
 
 
• /farmer
 
• /farmer /{farmer_id}
 
 
Note:
 
Although I mention that the use of the plural is the best practice, for some reason, if you stick to the singular, then stick to it in all your services. Do not mix the use of plural and singular numbers. That's why I'm not talking here about bad practice, but I'm just saying that this is not recommended. Please decide for yourself what is best for your application.
 
 

3. Documentation


 
Documenting software is a common practice for all developers. This practice should be followed in the implementation of REST applications. If you write useful documentation, it will help other developers understand your code.
 
The most common way to document REST applications is to document the endpoints listed in it, and describe the list of operations for each of them. There are many tools that allow you to do this automatically.
 
 
Below are the applications that help document REST services:
 
 
DRF Docs
 
Swagger
 
Apiary
 
 
Please share your experience in documenting your applications in the comments.
 
 

4. The version of your application


 
Any software develops over time. This may require different versions for all significant changes in the application. When it comes to the REST version of the application, it becomes one of the most discussed topics among the REST developer community.
 
 
There are two general ways to manage versions of REST applications:
 
 
1. The version URI.
 
2. Multimedia version.
 
 
URI version:
 
 
A simple example of what the URI version looks like:
 
host /v2 /farmers
 
host /v1 /farmers
 
 
Below are the main disadvantages of the way of creating versions using URI:
 
 
 
The existing URIs are crashed, all clients must update to the new URI.
 
The number of URI versions for management increases, which in turn increases the size of the HTTP cache for storing multiple versions of the URI. Adding a large number of duplicate URIs can affect the number of accesses to the cache and thus can reduce the performance of your application.
 
It is extremely inflexible, we can not just change the resource or a small set of them.
 
 
Multimedia version control:
 
This approach sends the version information in the header of each request. When we change the type and language of the multimedia URI, we move on to review the content based on the title. This method is the most preferred option for managing versions of REST applications.
 
 
Example of information in the title:
 
 
GET /account /5555 HTTP /???r3r3447.  
Accept: application /vnd.farmers.v1 + json
 
 
HTTP /??? OK
 
Content-Type: application /vnd.farmers.v1 + json
 
 
In the multimedia version control approach, the client can choose which version to request from the server. This method looks more preferable than the URI approach, but the complexity arises when caching queries with different versions that are passed through the header. In simple terms, when a client caches based on a URI, it's simple, but caching with a key as a multimedia type adds complexity.
 
 

5. Pagination


 
Sending a large amount of data via HTTP is not a good idea. Of course, there will be performance problems, since the serialization of large JSON objects will become expensive. Best practice is splitting the results into parts, and not sending all the records at once. Provide the ability to split results on a page using previous or next links.
 
 
If you use pagination in your application, one of the good ways to specify a link to pagination is to use the Link HTTP header option.
 
The following link will be useful to you.
 
 

6. Using SSL


 
SSL must be! You must always use SSL for your REST application. Access to your application will be from anywhere in the world, and there is no guarantee that it will be secured. With the growing number of incidents with cybercrime, we must ensure security for our application.
 
 
Standard authentication verification protocols make it easy to protect your application. Do not use the basic authentication mechanism. Use Oauth1.Oa or Oaurh2 for better security of your services. I would recommend Oauth2 personally because of its newest features.
 
 

7. HTTP methods


 
Designing operations on HTTP methods becomes easier when you know the characteristics of all HTTP methods. In one of the previous sections of this article, I insisted on using HTTP methods for operations instead of writing different service names for each operation. This section basically discusses the behavior of each HTTP method.
 
 
Below are two characteristics that must be determined before using the HTTP method:
 
 
 
Security: An HTTP method is considered safe when calling this method does not change the state of the data. For example, when you extract data using the GET method, this is safe because this method does not update the data on the server side.
 
Idempotency: when you get the same answer, how many times you call the same resource, it is known as idempotent. For example, when you try to update the same data on a server, the response will be the same for each query made with the same data.
 
 
Not all methods are safe and idempotent. Below is a list of methods that are used in REST applications and their properties are shown:
 
 
REST API Best Practices
 
REST HTTP methods
 
 
Below is a brief overview of each method and recommendations for their use:
 
 
 
GET: this method is safe and idempotent. It is usually used to extract information and has no side effects.
 
POST: this method is neither safe nor idempotent. This method is most widely used to create resources.
 
PUT: this method is idempotent. That's why it's better to use this method instead of POST to update the resources. Avoid using POST to update resources.
 
DELETE: as the name suggests, this method is used to remove resources. But this method is not idempotent for all queries.
 
OPTIONS: This method is not used for any manipulation of resources. But it is useful when the client does not know of other methods supported for the resource, and using this method, the client can get a different view of the resource.
 
HEAD: This method is used to request a resource from the server. It is very similar to the GET method, but HEAD must send a request and receive a response only in the header. According to the HTTP specification, this method should not use the body for a query and response.
 
 

8. Effective use of HTTP response codes


 
HTTP defines different response codes to tell the client various information about operations. Your REST application could effectively use all available HTTP codes to help the client correctly configure the response. The following is a list of HTTP response codes:
 
 
 
200 OK is the answer to the successful GET, PUT, PATCH or DELETE. This code is also used for POST, which does not lead to the creation.
 
201 Created - this status code is the response to the POST that results in the creation.
 
204 There is no content. This is the response to a successful request that will not return the body (for example, the DELETE query)
 
304 Not Modified - use this status code when the HTTP caching headers are in work
 
400 Bad Request - this status code indicates that the request is corrupted, for example, if the body can not be analyzed by
 
401 Unauthorized - If authentication data is not specified or is invalid. It is also useful to activate the auth pop-up window if the application is used from the
browser.  
403 Forbidden - when the authentication was successful, but the authenticated user does not have access to the resource
 
404 Not found - if a non-existent resource is requested
 
405 Method Not Allowed - when an HTTP method is requested that is not allowed for the authenticated user
 
410 Gone - This status code indicates that the resource in this endpoint is no longer available. Useful as a security answer for older versions of API
 
415 Unsupported Media Type. If the wrong content type
was specified as part of the request.  
422 Unprocessable Entity - used to check for errors
 
429 Too Many Requests - when the request is rejected due to the speed limit
 
 

Summary


 
I hope this article will be useful for understanding how to create your REST API. Here are the best practices, gathered on the basis of my experience and discussions with friends who worked on REST web services applications.
 
 
If you worked a lot on the design of the REST API, and if you feel that this article does not make any sense to you, I'm glad to hear your feedback. I would like to continue updating this discussion with more proven methods for developing the best API for your application.
 
 
Good reading. Thank you for visiting my blog.
+ +1 -

Add comment