API Design Specification----Restful

　　

Restful API Design Guide

Next I will introduce the design details of the 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 HTTPS protocol.

Second, the domain name

The API should be deployed under a dedicated domain name whenever possible.

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 (Versioning)

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 called 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.

For example, there is an API that provides information about zoos, as well as information about various animals and employees, and its path should be designed as follows.

HTTPS://api.example.com/v1/zooshttps://api.example.com/v1/animalshttps: // 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): Remove resources from the server (one or more items). POST (Create): Creates a new resource on the server. PUT (UPDATE): Updates the resource on the server (the client provides a full resource after the change). PATCH (UPDATE): Updates the resource on the server (the client provides changed properties). Delete: Deletes a resource from the server.

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 number of records is large, the server will 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=1：指定筛选条件

The design of the parameter allows 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.

State code (status Codes)

The status code and prompt information returned by the server to the user is usually the following (the HTTP verb corresponding to the status code in square brackets).

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。 201 CREATED - [POST /PUT/PATCH ]：用户新建或修改数据成功。 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务） 204 NO CONTENT - [DELETE]：用户删除数据成功。 400 INVALID REQUEST - [POST /PUT/PATCH ]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。 422 Unprocesable entity - [POST /PUT/PATCH ] 当创建一个对象时，发生一个验证错误。 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

See here for a complete list of status codes.

Viii. error handling (handling)

If the status code is 4xx, you should return an error message to the user. In general, error is used as the key name in the returned information, and error information is used as the key value.

{      error:  "Invalid API key" }Ix. Return of results

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 ：返回一个空文档

X. hypermedia API

The RESTful API is best done by hypermedia, which provides links to the returned results, connecting to other API methods, so that users do not look up documents and know what to do next.

For example, when a user makes a request to the root directory of api.example.com, a document is obtained.

{ "link" : {    "rel" :    "collection https://www.example.com/zoos" ,    "href" :   "https://api.example.com/zoos" ,    "title" :  "List of zoos" ,    "type" :   "application/vnd.yourformat+json" }}

The code above indicates that there is a link property in the document, and the user reads this property and knows what API to call next. Rel represents the relationship between this API and the current URL (collection relationship, and gives the collection URL), the href represents the path to the API, title represents the API's caption, and type represents the return type.

The design of the Hypermedia API is known as Hateoas. The GitHub API is the design that accesses api.github.com to get a list of URLs for all available APIs.

{    "current_user_url" :  "https://api.github.com/user" ,    "authorizations_url" :  "https://api.github.com/authorizations" ,    / / ... }

As you can see from the above, if you want to get information about the current user, you should go to the api.github.com/user and get the results below.

{    "message" :  "Requires authentication" ,    "documentation_url" :  "https://developer.github.com/v3" }

The above code indicates that the server gives the prompt information and the URL of the document.

Xi. Other

(1) The identity authentication of the API should use the OAuth 2.0 framework.

(2) The data format returned by the server should use JSON as much as possible to avoid using XML.

This article is reproduced from http://www.ruanyifeng.com/blog/2014/05/restful_api.html

API Design Specification----Restful