REST APIs and Designing Best Practices

APIs (Application Programming Interfaces) are necessary for applications or devices to connect and communicate with each other.

In this article, I will explain what REST Api is, which is vary popular one, and the best practice of designing it.

What is REST?

History of REST

1. REST was born in 2000, after SOAP.
2. Amazon started to use REST in 2003, and REST started to be used gradually instead of SOAP.
3. REST is superior to SOAP in some ways, such as the ability to use caching, better performance due to statelessness, support for many formats such as JSON and XML, and the ability to check operations by simply entering a URI, but security is inferior to SOAP in some cases.

REST Api and Architecture Style

REST is an abbreviation for Representational State Transfer, which was first announced by Roy Fielding in 2000.

It is one of the architectural styles.

What is architectural styles?

1. Architectural style is a design guideline, and just as there are Japanese and European architectural styles, there are various architectural styles.
2. There are many other architectural styles, such as object-oriented architecture style, microservice architecture style, etc.

REST is a combination of multiple architectural styles such as client-server architecture style, tiered architecture style, cache architecture style, etc.

Features of REST

REST has the following features:

1. Published with addressable URI.

   • Accessible by URI, such as https:/○○○○/example/rest/01
   • Responded in JSON or XML

2. The interface must be unified in the use of HTTP methods

   • Data can be used by using methods such as GET, POST, PUT, DELETE, HEAD, etc.

3. Statelessness

   • All information is thrown in the request, and the server does not retain the session information.
   • This makes it possible to reserve server resources and change servers flexibly according to the load of requests

4. Ability to connect to other information if the resource URI is known

   • The information being requested can contain hyperlinks. It is possible to connect from one link to another, and RESTful systems can smoothly link information to each other.

5. Return processing results in HTTP status code

   • Return results in status codes such as 200 (OK), 403 (Forbidden), 404 (Not Found), etc.

Web services that implement this architectural style of REST are called RESTful services.
The HTTP calling interface of a web system built according to such REST principles is called a REST API.

Best Practice of Development of REST API

The detailed rules may vary depending on your development team, but these are the basic rules:

1. Give names that are easily understood by humans.
2. Add a noun to the end of the URI, not a verb.
3. Give Nouns in the URI plural.
4. Return the processing result as an HTTP status code.
5. Include the API version in the URI.

So let's talk about it more with examples.

Step1. Give names that are easily understood by humans

1-1. Reveal that it's URI of api and don't duplicate words

ex)
❎ http://*api*.example.com/services/*api*/
✅ http://api.example.com/services/
✅ http://example.com/services/api

1-2. Unify the rules

If URI to obtain friend information is using a query parameter http://api.example.com/friends?id=100,
　
URI to post a message to the friend also should be using a query parameter　　　
✅ http://api.example.com/friends/messages?id=100.

Should not be
❎ http://api.example.com/friends/100/messages

and vise versa.

1-3. Avoid to create deeply nested URIs

ex)
❎ https://api.example.com/sports/1/players/2/friends
✅ https://api.example.com/players/2/friends
The further to the right URI goes, the more resources it will have as a subset.

Step2. Add a noun to the end of the URI, not a verb

GET method:
❎ https://api.example.com/v1/getItems
✅ https://api.example.com/v1/items

POST method:
❎ https://api.example.com/v1/news/createArticles
✅ https://api.example.com/v1/news/articles

Like these examples, avoid using verbs at the end of URIs as much as possible, since they are semantically understood by using the HTTP method at the time of the request.

Step3. Give Nouns in the URI plural

❎ https://api.example.com/v1/item/01
✅ https://api.example.com/v1/items/01

Generally, resources in a path are not one, but sets, like items (= multiple), so always use the plural form consistently.

Step4. Return the results with an HTTP status code

When an error occurs, return the processing result in the HTTP status code so that the API user can understand the cause of the error.

For example, the famous one 404 Not Found will be returned when the endpoint is valid but the resource itself does not exist.
For more information about HTTP status code, you can check it out here

Step5. Include the API version in the URI

The version of the API should be included. This will prevent users from being affected if the API changes over time.
Version management will allow you to change the API structure without compromising compatibility.

Summary

That's about REST and the best practice of designing Rest API. I think the rules are slightly different depending on the team, but I hope it helps you.

Comments

[Ankit Jain]

Well, this link is the Geeta/Bible for Rest API best practices. check it out for completeness: vinaysahni.com/best-practices-for-...