Restful API design specification

PDF Download address ：https://download.csdn.net/download/weixin_45525272/80429647

RESTful API design code

⼀、 What is? RESTful？

⼜ call REST（Representational State Transfer）,⼀ Kind of Software architecture ⻛ grid 、 Design style , Not the standard , It just provides ⼀ Set design principles and constraints . It mainly ⽤ Software for client and server interaction .

Its core is ⾯ To resources ,REST Specifically for the network should ⽤ Design and development methods , To reduce the complexity of development , carry ⾼ Scalability of the system .

stay RESTful Architecture , Each website represents ⼀ Kind of resources （resource）, So there can't be verbs in the website , Only nouns .

⼀ In general , The tables in the database are the same kind of records ” aggregate ”（collection）, therefore API Nouns in should also make ⽤ The plural , Unless there is no proper plural form , Such as ：weather.

Two 、 Design concepts and guidelines

• Everything on the network can be abstracted as resources (resource);
• Every resource has only ⼀ Resource ID for (resource identifier), Operations on resources do not change these identities ;
• All operations are stateless ;
• Layered system , Representation component ⽆ Can't understand the components outside the middle tier with which it interacts . By limiting system knowledge to a single layer , Can limit the complexity of the entire system , Promote the uniqueness of the bottom ⽴ sex .

3、 ... and 、 Why use RESTful API？

• Resources oriented （URI）, Interpretive ;
• Behavior （GET / POST / PUT / PATCH / DELETE） And resources （URI） Separate , Lighter weight ;
• Data description is simple , send ⽤JSON、XML、PROTOBUFFER You can fully cover , Mainly make ⽤JSON;

Four 、 agreement

API And ⽤ User's communication protocol ,⼀ General envoy ⽤HTTP agreement , Make ⽤HTTPS.

5、 ... and 、 domain name

We should try our best to API Deployed in specialized ⽤ Under domain name ：

https://api.example.com

If determined API It's simple , There will be no progress ⼀ Step expansion , Consider putting it under the primary domain name ：

https://example.org/api/

6、 ... and 、 edition

At every API Corresponding URL in , due ⼀ Version number , In order to upgrade the service in the future , All versions of the client can be used normally , as follows ：

https://api.example.com/v1/topics/
https://api.example.com/v2/topics/
https://api.example.com/v3/topics/

7、 ... and 、http request ⽅ type

Request mode	meaning
GET	Read （Read）
POST	newly build （Create）
PUT	to update （Update）, Usually all updates
PATCH	to update （Update）, It's usually a partial update
DELETE	Delete （Delete）

8、 ... and 、 route （ route ）

• Every ⽹ There must be no verbs in the address , Only nouns . And should make ⽤ The plural , except ⾮ There is no proper plural , Such as ：weather.

https://api.example.com/v1/topics/ —> All posts ⼦

• For resources under individual or class names , You can directly add specific id To represent , as follows ：

https://api.example.com/v1/topics/100001/info // id by 100001 My post ⼦ Details of
https://api.example.com/v1/users/12345/topics/ // id by 12345 Of ⽤ All posts under the account name ⼦

• More examples [ With request method ]

[GET] https://api.example.com/v1/topics/ — Get all posts ⼦( list )
[POST] https://api.example.com/v1/topics/ — New post ⼦
[PUT] https://api.example.com/v1/topics/100001 — Update the full post ⼦
[PATCH] https://api.example.com/v1/topics/100001 — Update post ⼦ Some information
[DELETE] https://api.example.com/v1/topics/100001 — Delete post ⼦
[GET] https://api.example.com/v1/groups/1/topics/ — Get all posts in a group ⼦( list )
[GET] https://api.example.com/v1/users/12345/profile — Get some ⽤ Household information
[PUT] https://api.example.com/v1/users/12345/profile — Update sth ⽤ Household information
[GET] https://api.example.com/v1/users/12345/labels — Get some ⽤ All labels

Nine 、 Filtering information （url in ? after ⾯ Parameters of ）

Reasons for using filtered information ：

1. single ⼀ Of url The path cannot represent all the scenes , Played a supplementary role ⽤;

   ?limit=10                   ： Specify the number of returned records 
   ?offset=10                  ： Specify where to start the return record .
   ?page=2&per_page=100 		： Designate the ⼏⻚, And every ⻚ Number of records .
   ?sortby=name&order=asc		： Specifies which attribute to sort the returned results by , And sort order .
   ?animal_type_id=1           ： Specify filter criteria 
   

2. Avoid multiple levels URL, Not conducive to expansion , The meaning is not clear , It's difficult to understand ;
   multistage URL：

   GET /authors/12/categories/2 //  What does it mean ？
   

   The right thing to do is ：

   GET /authors/12?categories=2
   

Ten 、 Status code

HTTP The status code is ⼀ Three digits , Divided into five categories ：

Category	meaning
1xx	Related information , Don't use
2xx	Successful operation
3xx	Redirect
4xx	Client error
5xx	Server error

Unless it is 500 and 404 error ,⼤ Partially make ⽤ 200 Status code is enough , The returned data format is as follows ：

11、 ... and 、 Other

（1）API Of ⾝ Certificates should use OAuth 2.0 frame .
（2） Data format returned by the server , Should be used as much as possible JSON, Avoid using XML.