REST API Best Practices
Hi, Habr! I present to your attention the translation of the article " REST API Best Practices " by Krishna Srinivasan.
REST is becoming a common approach for 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 accessible via 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 practies 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. Endpoints in the URL - noun, non verb
2. Plural
3. Documentation
4. Version of your application
5. Pagination
6. Using SSL
7. HTTP methods
8. Efficient use of HTTP response codes
One of the most common mistakes that REST application developers make is using verbs when naming endpoints. However, this is not the best practice. You should always use nouns instead of verbs.
Sample script:
We have an order for the development of REST web services that provide information about Indian farmers. The service should also implement functionality that provides such information as farmer income, crop names, farm addresses, and other information related to each farmer. Each farmer has a unique id.
In the same way, services providing information about crops and which farmer owns them should be implemented.
Best Practice:
We have a single endpoint that is responsible for all actions. In the example below, there is only one end point / farmers for all operations such as add, update, delete. 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 submit operations inside such formats as JSON, XML, RAML or use HTTP methods. Do not use the following symbols:
• / getFarmers
• / updateFarmers
• / deleteFarmers
• / getCrops
• / updateCrops
• / deleteCrops
Use the plural for your REST services. This is another hot topic for discussion among REST designers - the choice between single or multiple nouns to denote 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 best practice, for some reason, if you stick to the singular, stick to it in all of your services. Do not mix the use of the plural and singular numbers. Therefore, I do not speak here about bad practice, but simply say that it is not recommended. Please decide for yourself what is best for your application.
Documenting software is a common practice for all developers. This practice should be followed when implementing REST applications. If you write useful documentation, it will help other developers understand your code.
The most common way to document REST applications is documentation with the endpoints listed in it, and describing 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 documenting your applications in the comments.
Any software develops over time. This may require different versions for all significant changes to 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. URI version.
2. Multimedia version.
Version URI:
A simple example of what a URI version looks like:
host / v2 / farmers
host / v1 / farmers
The following are the main disadvantages of the way of creating versions using URIs:
Multimedia version control:
This approach sends version information in the header of each request. When we change the media type and language of the URI, we will proceed to review the content based on the title. This method is the most preferred option for managing versions of REST applications.
Sample information in the title:
GET / account / 5555 HTTP / 1.1
Accept: application / vnd.farmers.v1 + json
HTTP / 1.1 200 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 approach with a URI, but the difficulty arises when caching requests with different versions that are passed through the header. In simple terms, when a client caches on a URI basis, it is simple, but caching with a key as a multimedia type adds complexity.
Sending large amounts of data via HTTP is not a good idea. Of course, performance problems will arise, since the serialization of JSON large objects will become expensive. Best practice is splitting the results into parts, not sending all the records at once. Provide the ability to split results on a page using the preceding or following links.
If you use pagination in your application, one of the good ways to specify a link to a pagination is to use the Link HTTP header option.
The following link will be useful for you.
SSL should be! You should always use SSL for your REST application. Your application will be accessed from anywhere in the world, and there is no guarantee that it will be securely accessible. With the growing number of cybercrime incidents, we must ensure the security of 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.
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 focuses on the behavior of each HTTP method.
Below are two characteristics that must be defined before using the HTTP method:
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 HTTP methods
Below is a brief overview of each method and recommendations for their use:
HTTP defines various response codes to provide the client with various transaction information. Your REST application could efficiently use all available HTTP codes to help the client properly set up the response. The following is a list of HTTP response codes:
I hope this article will be useful for understanding how to create your own REST API. Here are the best practices based on my experience and discussion with friends who have worked on REST web services applications.
If you have worked a lot on the design of the REST API, and if you feel that this article has no meaning for you, I’m glad to hear your feedback. I would like to continue updating this discussion using more proven methods to develop a better API for your application.
Good read. Thanks for visiting my blog.
REST is becoming a common approach for 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 accessible via 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 practies 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. Endpoints in the URL - noun, non verb
2. Plural
3. Documentation
4. Version of your application
5. Pagination
6. Using SSL
7. HTTP methods
8. Efficient use of HTTP response codes
1. Endpoints in the URL - noun, non verb
One of the most common mistakes that REST application developers make is using verbs when naming endpoints. However, this is not the best practice. You should always use nouns instead of verbs.
Sample script:
We have an order for the development of REST web services that provide information about Indian farmers. The service should also implement functionality that provides such information as farmer income, crop names, farm addresses, and other information related to each farmer. Each farmer has a unique id.
In the same way, services providing information about crops and which farmer owns them should be implemented.
Best Practice:
We have a single endpoint that is responsible for all actions. In the example below, there is only one end point / farmers for all operations such as add, update, delete. 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 submit 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. Plural
Use the plural for your REST services. This is another hot topic for discussion among REST designers - the choice between single or multiple nouns to denote 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 best practice, for some reason, if you stick to the singular, stick to it in all of your services. Do not mix the use of the plural and singular numbers. Therefore, I do not speak here about bad practice, but simply say that it 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 when implementing REST applications. If you write useful documentation, it will help other developers understand your code.
The most common way to document REST applications is documentation with the endpoints listed in it, and describing 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 documenting your applications in the comments.
4. Version of your application
Any software develops over time. This may require different versions for all significant changes to 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. URI version.
2. Multimedia version.
Version URI:
A simple example of what a URI version looks like:
host / v2 / farmers
host / v1 / farmers
The following are the main disadvantages of the way of creating versions using URIs:
- Existing URIs are broken, all clients must update to the new URI.
- The number of version URIs to control increases, which in turn increases the size of the HTTP cache to store multiple versions of URIs. 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 version information in the header of each request. When we change the media type and language of the URI, we will proceed to review the content based on the title. This method is the most preferred option for managing versions of REST applications.
Sample information in the title:
GET / account / 5555 HTTP / 1.1
Accept: application / vnd.farmers.v1 + json
HTTP / 1.1 200 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 approach with a URI, but the difficulty arises when caching requests with different versions that are passed through the header. In simple terms, when a client caches on a URI basis, it is simple, but caching with a key as a multimedia type adds complexity.
5. Pagination
Sending large amounts of data via HTTP is not a good idea. Of course, performance problems will arise, since the serialization of JSON large objects will become expensive. Best practice is splitting the results into parts, not sending all the records at once. Provide the ability to split results on a page using the preceding or following links.
If you use pagination in your application, one of the good ways to specify a link to a pagination is to use the Link HTTP header option.
The following link will be useful for you.
6. Using SSL
SSL should be! You should always use SSL for your REST application. Your application will be accessed from anywhere in the world, and there is no guarantee that it will be securely accessible. With the growing number of cybercrime incidents, we must ensure the security of 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 focuses on the behavior of each HTTP method.
Below are two characteristics that must be defined before using the HTTP method:
- Security: The 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, it 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 the server, the response will be the same for each request 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 HTTP methods
Below is a brief overview of each method and recommendations for their use:
- GET: This method is safe and idempotent. Usually used to extract information and has no side effects.
- POST: this method is neither secure nor idempotent. This method is most widely used to create resources.
- PUT: this method is idempotent. That is why it is better to use this method instead of POST to update resources. Avoid using POST to update resources.
- DELETE: as the name suggests, this method is used to delete 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 the 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 should send a request and receive a response only in the header. According to the HTTP specification, this method should not use a body for request and response.
8. Efficient use of HTTP response codes
HTTP defines various response codes to provide the client with various transaction information. Your REST application could efficiently use all available HTTP codes to help the client properly set up the response. The following is a list of HTTP response codes:
- 200 OK is the answer to successful GET, PUT, PATCH or DELETE. This code is also used for POST, which does not lead to creation.
- 201 Created - this status code is a response to POST, which leads to creation.
- 204 No content. This is a response to a successful request that will not return a body (for example, a DELETE request)
- 304 Not Modified — use this status code when HTTP caching headers are in operation.
- 400 Bad Request - this status code indicates that the request is malformed, for example, if the body cannot be analyzed
- 401 Unauthorized - If authentication data is not specified or invalid. It is also useful to activate the auth popup window if the application is being used from a browser.
- 403 Forbidden - when 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 an authenticated user.
- 410 Gone — This status code indicates that the resource is no longer available at this endpoint. Useful as a security response for older APIs.
- 415 Unsupported Media Type. If the wrong content type was specified as part of the request
- 422 Unprocessable Entity - used for error checking.
- 429 Too Many Requests - when the request is rejected due to speed limit
Summary
I hope this article will be useful for understanding how to create your own REST API. Here are the best practices based on my experience and discussion with friends who have worked on REST web services applications.
If you have worked a lot on the design of the REST API, and if you feel that this article has no meaning for you, I’m glad to hear your feedback. I would like to continue updating this discussion using more proven methods to develop a better API for your application.
Good read. Thanks for visiting my blog.
Source: https://habr.com/ru/post/351890/
All Articles