RESTful API Design Guide

The Web application is divided into two parts, front end and back end. The current development trend is the front-end equipment (mobile phones, tablets, desktop computers, other special equipment ...).
Therefore, there must be a unified mechanism to facilitate the communication of different front-end devices to the backend. This led to the popularity of API architecture, and even the "API first" design idea. RESTful API is currently a relatively mature set of Internet Application API design theory. Today, we mainly introduce the design details of RESTful API and discuss how to design a reasonable and useful API.

First, the agreement
The API communicates with the user protocol, always using the HTTP protocol.
Second, the domain name
Should try to deploy the API under a dedicated domain name

https://api.example.com

If you determine that the API is simple, there is no further extension, consider placing it under the primary domain name

https://example.org/api/

Third, version
The version number of the API should be placed in the URL

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

Another option is to place the version number in the HTTP header information, but not as convenient and intuitive as placing the URL. GitHub uses this approach.
Iv. Path (Endpoint)
The path is also known as the "end point (Endpoint)", which represents the specific URL of the API.
In a restful architecture, each URL represents a resource (resource), so there can be no verbs in the URL, only nouns, and nouns often correspond to the table names in the database. In general, the tables in the database are "collections (collection)" of the same record, so nouns in the API should also use complex numbers.
Distance, there is an API that provides information about the zoo and also includes information about the various animals and employees, and its path should be designed as follows

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

V. HTTP verbs
For the specific operation type of the resource, it is represented by an HTTP verb.
The usual HTTP verbs have the following five (the corresponding SQL command in parentheses)

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

There are also two infrequently used HTTP verbs

- HEAD：获取资源的元数据- OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的

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：删除某个指定动物园的指定动物

Vi. filtering information (Filtering)
If the amount of data logged is large, the server may not be able to return them to the user. The API should provide parameters to filter the returned results.
The following are some common parameters:

- ?limit=10：指定返回记录的数量- ?offset=10：指定返回记录的开始位置- ?page=2&per_page=100：指定第几页，以及每页的记录数- ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序- ?animal_type_id：指定筛选条件

Parameter settings allow redundancy, which allows the API path and URL parameters to be duplicated occasionally. For example, the meaning of Get/zoo/id/animals and Get/animals?zoo_id=id is the same.
Seven, status code
The status code and prompt information returned by the server to the user is usually the following (the square brackets are the HTTP verbs corresponding to the status code).

- 200 OK [GET]：服务器成功返回用户请求的数据，该操作是幂等的(Idempotent)- 201 CREATE [POST/PUT/PATCH]：用户新建或者修改数据成功

RESTful API Design Guide