RESTful API design study notes

This article mainly refers to Ruan Yifeng's RESTful API Design Guide

1. Agreement

The communication protocol between the API and the user, always use HTTPs

2. Domain Name

You should try to deploy the API under a dedicated domain name:

https://api.example.com

If the API is very simple and will not be further extended, consider putting it under the main domain name:

https://example.com/api/

3. Version

The version number of the API should be put into the URL:

https://api.example.com/v1/

Alternatively, put the version number in the HTTP header, but it is not as convenient and intuitive as the URL. (But what if the API is placed under the main domain name? Does adding the version number make the API redundant?)

4. Path

In the RESTful architecture, each URL represents a resource, so there can be no verbs in the URL, only nouns , and the nouns used often correspond to the table names in the database. In general, tables in a database are "collections" of the same kind of records, so nouns in the API should also be plural .

For example, if there is an API that provides information about a zoo, and also includes information about various animals and employees, its path should be designed like this:

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

A few points to note in URIs:

• do not capitalize
• Use the middle bar, -not the lower bar_
• The parameter list needs to be encoded
• The noun in the URI represents a collection of resources, using the plural form

5. HTTP verbs

There are five commonly used HTTP verbs (the corresponding SQL commands in parentheses):

GET（SELECT）：从服务器取出资源（一项或多项）
POST（CREATE）：从服务器新建一个资源
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整属性）
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）
DELETE（DELETE）：从服务器删除资源

Here are some examples:

GET  /zoos：列出所有动物园
POST  /zoos：新建一个动物园
GET  /zoos/ID：获取某个指定动物园的信息
PUT  /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH  /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE  /zoos/ID：删除某个动物园
GET  /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE  /zoos/ID/animals/ID：删除某个指定动物园的指定动物

The RESTful architectural style has the characteristics of a unified interface, that is, different http methods are used to express different behaviors, and forms like /zoos/add, /zoos/ID/delete no longer appear.

In the RESTful standard, both PUT and PATCH can be used for modification operations. The difference between them is that PUT needs to submit the entire object, while PATCH only needs to submit the modified information. But in my opinion, there is no need for such trouble in practical applications, so I always use PUT and only submit modified information.

For more analysis of PUT and PATCH, you can see here

6. Filter information

If the number of records is large, it is impossible for the server to return them all. The API should provide parameters to filter the returned results:

?limit=10
?offset=10
?page=2&per_page=100
?sortby=name&order=asc
?animal_type_id=1

Parameters are designed to allow for redundancy, which allows for occasional repetition of API paths and URL parameters. For example, GET /zoos/ID/animals and GET /animals?zoo_id=ID have the same meaning

7. Status code

200 OK - [GET]：服务器成功返回请求的数据
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功
204 NO CONTENT - [DELETE]：用户删除数据成功
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改的操作
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户无法判断发出的请求是否成功（该状态码是服务器自动生成返回的，不能手动将状态码返回 500）

There are many servers that always set the return status code to 200, and then customize some status codes in the return body to indicate the status code of the result returned by the server. Since RESTful uses the HTTP protocol directly, its status code should also try to use the status code of the HTTP protocol.

8. Error Handling

If the status code is 4xx, an error message should be returned to the user.

{
  error: "Invalid API key"
}

9. Return the result

For different operations, the results returned by the server to the user should conform to the following specifications.

GET  /collection：返回资源对象的列表（数组）
GET  /collection/resource：返回单个资源对象
POST  /collection：返回新生成的资源对象
PUT  /collection/resource：返回完整的资源对象
PATCH  /collection/resource：返回完整的资源对象
DELETE  /collection/resource：返回一个空文档

10. Reference Links

• https://api.github.com/