RESTful Interface Design Specification

1. Domain Name

The API should try to be deployed under a dedicated domain name.

https://api.example.com

If it is determined API is very simple, there will be no further extension may be considered placed under the main domain name.

https://example.org/api/

2. version (Versioning)

API version number should be placed in URL.

http://www.example.com/app/1.0/foo

http://www.example.com/app/1.1/foo

http://www.example.com/app/2.0/foo

Another approach is the version number in the HTTP header information, but not as into convenient and intuitive URL. Github on the use of this practice.

Because different versions, can be understood as different manifestations of the same resources, so we should use the same URL. The version number can be distinguished in the Accept header field of the HTTP request (see the Versioning the REST Services ):

Accept: vnd.example-com.foo+json; version=1.0

Accept: vnd.example-com.foo+json; version=1.1

Accept: vnd.example-com.foo+json; version=2.0

3. Path (Endpoint)

Path, also known as "the end" (endpoint), represent specific URL API, each URL represents a resource (resource)

(1) resources as a URL, only nouns, verbs can not have, but the term is often used in correspondence with the name of the database table.

For example, the following is a good example:

/getProducts
/listOrders
/retreiveClientByOrder?orderId=1

For a simple structure, you should always use the term. In addition, the method may operate using an HTTP URL resource names separated.

GET /products ：将返回所有产品清单
POST /products ：将产品新建到集合
GET /products/4 ：将获取产品 4
PATCH（或）PUT /products/4 ：将更新产品 4

(2) API should be used in plural nouns. Whether child resources or all resources.

For example, to obtain products API can be defined

获取单个产品：http://127.0.0.1:8080/AppName/rest/products/1
获取所有产品: http://127.0.0.1:8080/AppName/rest/products

3. HTTP verb

For particular resource type of operation, represented by the HTTP verbs.

Common HTTP verbs have the following four (in brackets is the corresponding SQL commands).

• GET (SELECT): Remove the resource from the server (one or more).
• POST (CREATE): a new resource on the server.
• PUT (UPDATE): update the resource (after the complete resources provided by the client to change) in the server.
• DELETE (DELETE): Delete the resource from the server.

There are three less common HTTP verbs.

• PATCH (UPDATE): (provide property change of client) the server update (update) resources.
• HEAD: Gets the metadata resources.
• OPTIONS: access to information, which properties on the resources of the client can be changed.

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

4. Information filtering (Filtering)

If a large number of records, the server can not all they are returned to the user. API should provide parameters, filtering results are returned.

Here are some common parameters. query_string query string and subsequent column address after the question mark data, the format: name = xx & sss = xxx

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

The redundancy allows the design parameters, i.e. parameters allow API and URL path occasional duplicate. For example, GET / zoos / ID / animals and GET / animals? Zoo_id = ID is the same meaning.

6. Status Code (Status Codes)

Server returns to the user code and status message, a number of common are the following (in brackets is the HTTP status code corresponding verb).

• 200 OK - [GET]: the server returns the data requested by the user successfully
• 201 CREATED - [POST / PUT / PATCH]: new or modified user data successfully.
• 202 Accepted - [*]: indicates a request has been queued into the background (asynchronous task)
• 204 NO CONTENT - [DELETE]: Delete user data successfully.
• 400 INVALID REQUEST - [POST / PUT / PATCH]: request issued by a user mistake, the server does not operate new or modified data
• 401 Unauthorized - [*]: indicates that the user does not have permission (Token, username, password error).
• 403 Forbidden - [*] indicates that the user is authorized (and 401 relative error), but access is prohibited.
• 404 NOT FOUND - [*]: user issues a request for recording is not present, the server is not operated, the operation is idempotent.
• 406 Not Acceptable - [GET]: the format requested by the user is not available (such as JSON format requested by the user, but only the XML format).
• 410 Gone - [GET]: user request resources are permanently removed, and will not be obtained.
• 422 Unprocesable entity - [POST / PUT / PATCH] When an object is created, a verification error occurs.
• 500 INTERNAL SERVER ERROR - [*]: server error occurs, the user will be unable to determine whether the request is sent successfully.

A complete list of status codes see here or here .

7. Error Handling (Error handling)

If the status code 4xx, the server should return an error message to the user. In general, the error information will be returned as the key name as a key to the error message.

{
    error: "Invalid API key"
}

8. Back Results

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

• GET / collection: Returns the resource object list (array)
• GET / collection / ID: return a single resource object (JSON)
• POST / collection: Returns the newly created resource object (json)
• PUT / collection / ID: Back to full resource object (json)
• DELETE / collection / ID: returns an empty document (the empty string)

9. Hypermedia (Hypermedia API)

RESTful API is best to do Hypermedia (ie the returned results provide links, even to other API methods), so that the user does not check the documents, but also know what to do next.

For example, Github's API is this design, visit api.github.com will get a list of URLs of all available API.

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

It can be seen from the above, if you want to get the current user's information, should go visit api.github.com/user , and then I get the following results.

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

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

10. Other

The server returns data formats, you should try to use JSON, avoid the use of XML.