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.
- REST was born in 2000, after SOAP.
- Amazon started to use REST in 2003, and REST started to be used gradually instead of SOAP.
- 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 is an abbreviation for Representational State Transfer, which was first announced by Roy Fielding in 2000.
It is one of the architectural styles.
- Architectural style is a design guideline, and just as there are Japanese and European architectural styles, there are various architectural styles.
- 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.
REST has the following features:
Published with addressable URI.
- Accessible by URI, such as
- Responded in JSON or XML
- Accessible by URI, such as
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.
- 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
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.
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.
The detailed rules may vary depending on your development team, but these are the basic rules:
- Give names that are easily understood by humans.
- Add a noun to the end of the URI, not a verb.
- Give Nouns in the URI plural.
- Return the processing result as an HTTP status code.
- Include the API version in the URI.
So let's talk about it more with examples.
If URI to obtain friend information is using a query parameter
URI to post a message to the friend also should be using a query parameter
Should not be
and vise versa.
The further to the right URI goes, the more resources it will have as a subset.
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.
Generally, resources in a path are not one, but sets, like items (= multiple), so always use the plural form consistently.
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
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.
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.