6 RESTful specification

https://www.cnblogs.com/alice-bj/p/9258121.html

1. What is RESTful

REST has nothing to do with technology, represent a style of software architecture, REST is Representational State Transfer short, the Chinese translation is "to characterize the state of the transfer."

REST resources have to look at from the perspective of the entire class network, which will be distributed in the network resource identified by a URL node, characterized by access to resources through URL client application, access to these applications characterize the resulting change the status of these.

All of the data, but was acquired by the network or the operation (CRUD) data, are the resources, all the data as a resource is different from other REST architectural style of the most essential attributes.

For this resource-oriented REST architectural style, it was suggested that a new structure concept, namely: resource-oriented architecture (ROA: Resource Oriented Architecture).

2, RESTful API design

• API and user's communication protocol, always using HTTPs protocol .
• domain name 
  • https://api.example.com API will try to deploy a dedicated domain name (there will be cross-domain problems)
  • https://example.org/api/ API is very simple
• version
  • URL, such as: https: //api.example.com/v1/
  • The first cross-domain request, send multiple requests initiator
• Path, everything is on the CTV network resources, all represented a noun (plural available)
  • https://api.example.com/v1/zoos
  • https://api.example.com/v1/animals
  • https://api.example.com/v1/employees
• method
  • GET: Remove the resource (one or more) from the server
  • POST: Create a new resource on the server
  • PUT: update the resource on the server (after complete resources provided by the client to change)
  • PATCH: updated resource on the server (the client provides a property changes)
  • DELETE: delete a resource from the server
• Filtered, passed through a search condition parameters uploaded in the form url
  • https://api.example.com/v1/zoos?limit=10: Specifies the number of records returned
  • https://api.example.com/v1/zoos?offset=10: Returns the specified record start position
  • https://api.example.com/v1/zoos?page=2&per_page=100: Specifies the first few pages, as well as the number of records per page
  • https://api.example.com/v1/zoos?sortby=name&order=asc: Specifies which returns the results sorted by attribute, and sort order
  • https://api.example.com/v1/zoos?animal_type_id=1: Specify Filter Conditions
• status code

200 OK - [GET]: the server returns the data requested by the user successfully, the operation is idempotent (Idempotent). 
201 CREATED - [POST / PUT / PATCH]: new or modified user data successfully. 
202 Accepted - [*]: represents 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 create or modify the operation data, the operation is idempotent. 
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. 

For more see here: http: //www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

• Error processing, when the status code 4xx, should return an error message, error as a key.

{
    error: "Invalid API key"
}

• Return 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 / Resource: return a single resource object 
POST / collection: return to the newly created resource object 
PUT / collection / resource: returns the full resource object 
PATCH / collection / resource: return complete resource object 
DELETE / collection / resource: returns an empty document

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

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

　　

 

   Excerpt from: http: //www.ruanyifeng.com/blog/2014/05/restful_api.html 

　　　　   http://www.cnblogs.com/yuanchenqi/articles/8742684.html

　　　　   http://www.cnblogs.com/wupeiqi/articles/7805382.html

 　　　 　https://www.cnblogs.com/liwenzhou/p/8543035.html