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 -

Comments 23

Offline
morning world
morning world 11 November 2018 11:37
This is truly a great  read for me. I have bookmarked it and I am looking forward to reading new  articles. Keep up the good work!.  Portland  OR
Offline
morning world
morning world 12 November 2018 08:50
Thanks so  much for sharing this awesome info! I am looking forward to see more postsby  you! טיולים  מאורגנים
Offline
Anna Sally
Anna Sally 24 November 2018 11:52
Their expertise in project management and communication increases productivity.  Their expertise in Chemical/Oil & Gas Directory is no less.  The assigned resources are capable, punctual and reliable.

Offline
life time
life time 9 December 2018 18:52
Thanks for the blog  post buddy! Keep them coming... Oscar  awards 2019 winners
Offline
morning world
morning world 12 December 2018 15:55
Thanks for the blog  loaded with so many information. Stopping by your blog helped me to get what  I was looking for. Reliability  Testing


I read  that Post and got it fine and informative. טיסות  בפסח
Offline
fuzail faisal
fuzail faisal 13 December 2018 17:08
howdy,  your websites are really good. I appreciate your work.  Rushmore  trailer in mo
Offline
fuzail faisal
fuzail faisal 15 December 2018 21:01
Super-Duper site! I  am Loving it!! Will come back again, Im taking your feed also, Thanks. UFC  live online
Offline
Anna Sally
Anna Sally 16 December 2018 11:24
I absolutely hate coupon codes that don't work! The great thing about GetACode.com is that they guarantee their codes will work (or they'll give you a gift card from Amazon) deals
Offline
Anna Sally
Anna Sally 16 December 2018 17:53
Really I enjoy your  site with effective and useful information. It is included very nice post  with a lot of our resources.thanks for share. i enjoy this post.Used  Testing Equipment
Offline
Anna Sally
Anna Sally 17 December 2018 14:48
I am unable to read articles online very often, but I’m glad I did today.  This is very well written and your points are well-expressed.  Please, don’t ever stop writing. verchromte  Kolbenstangen

Offline
fuzailfaisal
fuzailfaisal 20 December 2018 15:16
I admire this article for the well-researched content and excellent wording.  I got so involved in this material that I couldn’t stop reading.  I am impressed with your work and skill.  Thank you so much. walmart  schedule
Offline
fuzail
fuzail 22 December 2018 14:46
I have been checking  out a few of your stories and i can state pretty good stuff. I will  definitely bookmark your blog rock  music
Offline
sohail khatri
sohail khatri 22 December 2018 15:52
it is the pleasing of facts i have been disturbing to find. thanks for scripting this statistics. It has proved utmost useful for me.บอลออนไลน์
Offline
Anna Sally
Anna Sally 23 December 2018 20:16
I wanted to thank you for this great read!! I definitely enjoying every little bit of it I have you bookmarked to check out new stuff you post.windstream speed test

Offline
life time
life time 24 December 2018 11:13
Awesome article, it  was exceptionally helpful! I simply began in this and I'm becoming more  acquainted with it better! Cheers, keep doing awesome! onlinemusicpromotion
Offline
charlos john
charlos john 24 December 2018 17:40
Wow, What a Excellent  post. I really found this to much informatics. It is what i was searching  for.I would like to suggest you that please keep sharing such type of  info.Thanks  Zahnärzte  Düsseldorf
Offline
Anna Sally
Anna Sally 26 December 2018 17:55
Excellent .. Amazing  .. I’ll bookmark your blog and take the feeds also…I’m happy to find so many  useful info here in the post, we need work out more techniques in this  regard, thanks for sharing.  dog  grooming miami
Offline
sohail khatri
sohail khatri 7 January 2019 21:16
i like travelling sites in my take a seat in judgment not guilty grow to be old. i've visited many sites but did no longer regard as swine any web site greater efficient than yours. thank you for the nudge! cardone university review
Offline
asd
asd 10 January 2019 21:23
remarkable call i might sooner or later to thank you for the efforts you've got made in scripting this tempting and knowledgeable article.spotistar.com

Offline
voyance 15
voyance 15 12 January 2019 14:42
This content is written very well.  Your use of formatting when making your points makes your observations very clear and easy to understand.  Thank you.voyance 15


Offline
fuzail
fuzail 12 January 2019 16:20
What a fantabulous post this has been. Never seen this kind of useful post. I am grateful to you and expect more number of posts like these. Thank you very much. דילים  לחול

Offline
asd
asd 12 January 2019 16:30
You create for that excuse many brilliant points right here that I admittance your article a couple of length.  Your views are in accordance bearing in mind my personal for the most component.  that is big content material for your readers.Back pain


Offline
Hassan1102
Hassan1102 Yesterday, 16:08
I wanted to thank you  for this excellent read!! I definitely loved every little bit of it. I have  you bookmarked your site to check out the new stuff you post.
google  pva

Add comment