Restful interface specification

1.Restful

　　REST The full name is Representational State Transfer, Chinese means to express （ Editor's note ： Representational state transition ）

　　RESTful It's a definition Web API Interface design style , It is especially suitable for the application mode of front and rear end separation .
　　 The idea of this style is that the back-end development task is to provide data , What we provide externally is the access interface of data resources , So when defining interfaces , Client access URL The path represents the data resource to be operated .
　　 in fact , We can use any framework to achieve compliance with restful canonical API Interface .
　　RESTful As the most popular  API  design code , It must have its unique charm ： Powerful 、 brief introduction 、 Easy to use 

2.Restful Ten interface specifications of

# 10 Rules
1. Data security ：
    url Links are generally used https Protocol for transmission notes ： use https agreement , It can improve the security in the process of data interaction

2. Interface feature representation , You know it's a api Interface
    - use api Keyword identification interface url：
      - [https://api.baidu.com](https://api.baidu.com/)
      - https://www.baidu.com/api
      notes ： notice api The word , On behalf of the request url The link is to complete the data interaction between the front and back stations
      - Luffy's interface ：https://api.luffycity.com/api/v1/course/free/

3. Multiple data versions coexist
    - stay url The link identifies the data version
    - https://api.baidu.com/v1
    - https://api.baidu.com/v2
    notes ：url In the link v1、v2 It's the embodiment of different data versions （ Only when a data resource has multiple versions ： For example, add interfaces to the original version , Similar revision , You also need to ensure that the old version can be used ）

4. Data is a resource ( They all use nouns )
    The interface is generally used to complete the data interaction between the front and the back , Interactive data is called resource
    https://api.baidu.com/users
    https://api.baidu.com/books
    https://api.baidu.com/book
    notes ： It is generally advocated to use the plural form of resources , stay url Do not use verbs to operate resources in links , Error model ：https://api.baidu.com/delete-user
    A special interface can have Verbs , Because these interfaces generally do not have a clear resource , Or the verb is the core meaning of the interface
    https://api.baidu.com/place/search
    https://api.baidu.com/login

5. Resource operation is determined by the request mode （method）
    - Operating resources usually involves adding, deleting, modifying and querying , We provide a request method to identify the addition, deletion, modification and query actions
      - https://api.baidu.com/books - get request ： Get all books
      - https://api.baidu.com/books/1 - get request ： Get the primary key as 1 The book of
      - https://api.baidu.com/books - post request ： Add a new book
      - https://api.baidu.com/books/1 - put request ： Change the primary key as a whole to 1 The book of
      - https://api.baidu.com/books/1 - patch request ： Change the primary key to 1 The book of
      - https://api.baidu.com/books/1 - delete request ： Delete the primary key as 1 The book of

6. Filter , By means of url Pass search terms in the form of upload parameters
    - https://api.example.com/v1/zoos?limit=10： Specify the number of returned records
    - https://api.example.com/v1/zoos?offset=10： Specify where to start the return record
    - https://api.example.com/v1/zoos?page=2&per_page=100： Specify page , And the number of records per page
    - https://api.example.com/v1/zoos?sortby=name&order=asc： Specifies which attribute to sort the returned results by , And sort order
    - https://api.example.com/v1/zoos?animal_type_id=1： Specify filter criteria

7. Response status code
    7.1 Normal response
    - Response status code 2xx
      - 200： Regular requests
      - 201： Create success
   7.2 Redirect response
    - Response status code 3xx
      - 301： Permanent redirection
      - 302： Redirect temporarily
   7.3 Client exception
    - Response status code 4xx
      - 403： Request no permission
      - 404： The request path does not exist
      - 405： The request method does not exist
    7.4 Server exception
    - Response status code 5xx
      - 500： Server exception

8. Error handling , Error message expected ,error treat as key
    {
        error: " No permission to operate "
    }

9. Return results , For different operations , The results returned by the server to the user should conform to the following specifications
    GET /collection： Returns a list of resource objects （ Array ）
    GET /collection/resource： Return a single resource object
    POST /collection： Return the newly generated resource object
    PUT /collection/resource： Returns the complete resource object
    PATCH /collection/resource： Returns the complete resource object
    DELETE /collection/resource： Return an empty document

10. need url Requested resources ： Request links that require access to resources
    # Hypermedia API,RESTful API Better do Hypermedia, That is, the link is provided in the returned result , Connect to others API Method , Make users not look up documents , And know what to do next
    {
            "status": 0,
            "msg": "ok",
            "results":[
                {
                    "name":" KFC ( Luo Restaurant )",
                    "img": "https://image.baidu.com/kfc/001.png"
                }
                ...
                ]
        }