It is a kind of web Software structured API Development style , Notice that it just represents a style , Does not represent a constraint 、 standard .

One 、 agreement 、 Domain name and version

Try to make ⽤https agreement , send ⽤ Exclusive domain name to provide API service , And in URL⾥ mark api edition , as follows

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

Two 、 URI( system ⼀ Resource identifier )

stay RESTful Architecture , Every ⽹ Address representative ⼀ Species resources （resource）, This ⽹ The contact address is URI(uniform resource identifier), Sometimes called URL(uniform resource locator). because URI Corresponding ⼀ Species resources , therefore ⾥⾯ There can't be verbs , 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 .

https://api.example.com/v1/users
⽤ User list resource address

https://api.example.com/v1/users/{id}
⽤ Household id=5 resources . Be careful ： this ⾥ yes users/5,⽽ No user/5,API Nouns in should make ⽤ The plural .⽆ On ⼦ Resources or all resources .

https://api.example.com/v1/users/{id}/articles
⽤ Household id=5 Published ⽂ Chapter list

Not RestFul Design , We used to write like this ：

http://xxx.com:8080/get/getArticle ( Search article )
http://xxx.com:8080/post/addArticle ( New article )
http://xxx.com:8080/update/updateArticle ( Update article )
http://xxx.com:8080/delete/deleteArticle ( Delete articles )

RestFul Design style ：

GET http://xxx.com:8080/get/articles（ Search article ）
POST http://xxx.com:8080/post/articles（ New article ）
PUT http://xxx.com:8080/update/articles（ New article ）
DELETE http://xxx.com:8080/dalete/articles（ Delete articles ）

3、 ... and 、HTTP Verb

For the specific operation type of resources , from HTTP The verb means .
often ⽤ Of HTTP The verb has the following ⾯ four （ Brackets ⾥ Is the corresponding SQL command ）

GET（SELECT）： Get resources from the server （⼀ Item or items ）.
POST（CREATE）： Create a new server ⼀ A resource .
PUT（UPDATE）： Update resources on the server （ The client provides complete resources after the change ）.
DELETE（DELETE）： Remove resources from server .

There are three not often ⽤ Of HTTP Verb .

PATCH（UPDATE）： Update on the server ( to update ) resources （ Client provides changed properties ）.
HEAD： Get the metadata of the resource .
OPTIONS： pick up information , Which properties of the resource can be changed by the client .

Four 、 Filtering information （Filtering）

If there are a lot of records , The server cannot return them all to ⽤ Household .API Parameters should be provided , Filter return results .
Next ⾯ yes ⼀ More often ⻅ Parameters of .

?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

5、 ... and 、 Status code （Status Codes）

Server to the ⽤ Status code and prompt information returned by the user , often ⻅ There are the following ⼀ some （⽅ In parentheses is the... Corresponding to the status code
HTTP Verb ）.
200 OK - [GET]： The server successfully returned ⽤ Data requested by the user
201 CREATED - [POST/PUT/PATCH]：⽤ User successfully created or modified data .
202 Accepted - [*]： Express ⼀ A request has entered ⼊ Backstage queue （ Asynchronous task ）
204 NO CONTENT - [DELETE]：⽤ User deleted data successfully .
400 INVALID REQUEST - [POST/PUT/PATCH]：⽤ There is an error in the request sent by the user , No access to the server
⾏ Create or modify data
401 Unauthorized - [*]： Express ⽤ User does not have permission （ token 、⽤ Account name 、 Wrong password ）.
403 Forbidden - [*] Express ⽤ The customer is authorized （ And 401 Error relative ）, But access is forbidden ⽌ Of .
404 NOT FOUND - [*]：⽤ The request sent by the user is for a non-existent record , No access to the server ⾏ operation ,
406 Not Acceptable - [GET]：⽤ The format requested by the user is not available （⽐ Such as ⽤ Customer request JSON Format , but
It's just XML Format ）.
410 Gone -[GET]：⽤ The resource requested by the user is permanently deleted , And it won't come back .
422 Unprocesable entity - [POST/PUT/PATCH] When creating a ⼀ When you are an object , Hair ⽣⼀ A test
error .
500 INTERNAL SERVER ERROR - [*]： The server sends ⽣ error ,⽤ The household will ⽆ Cannot judge whether the request is
Is it successful .

6、 ... and 、 Error handling

If the status code is 4xx, The server should report to ⽤ The user returns an error message .⼀ In general , The information returned will be error As a key name , The error message can be used as the key value .

{

error: "Invalid API key"
}

7、 ... and 、 Return results

GET /collection： Returns a list of resource objects （ Array ）
GET /collection/resource： Return a single resource object
POST /collection： Return to new ⽣ Become a resource object
PUT /collection/resource： Returns the complete resource object
PATCH /collection/resource： Returns the complete resource object
DELETE /collection/resource： return ⼀ Empty ⽂ files