Detailed explanation of web API interface and restful specifications

What is a web API interface?

Clarify the request method, provide the parameters required by the corresponding backend, and request the url link to get the response data from the backend

Request method: get, post, put, patch. ...

Request parameters: key-value type data in json or xml format

Response result: return key-value type data in json or xml format

How to write an interface?

Write the url link with reference to a certain rule (specification), and formulate the request method, request data and response results according to the rules

Interface specification: webapi interface specification: restful

RESTful introduction

REST has nothing to do with technology. It represents a software architecture style. REST is the abbreviation of Representational State Transfer, and the Chinese translation is "Representation state transfer" or "presentation layer state transformation".

Domain name

Use the api keyword to identify the interface url

https://api.example.com
https://example.org/api/

Note: If you see the word api, it means that the request url link is before completion

Version of background data interaction

1. Put the version information in the URL, such as:

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

v1, v2 represents different data versions Withdrawal, the premise is that a data resource has multiple versions

2. Put the version information in the request header.

url path

We regard everything on the Internet as a resource and use nouns to express it (generally plural form)

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

In the url link Rewards do not appear verbs that operate resources

Error demonstration:https://api.baidu.com/delete-user

Verbs can appear in special interfaces because these The interface generally does 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

method request method

GET: Get the resource (one or more items) from the server )

POST: Create a new resource on the server

PUT: Update the resource on the server (the client provides the changed complete resource)

PATCH: Update the resource on the server (client The changed attributes are provided by the client)

DELETE: Delete resources from the server

Filtering

Pass search conditions in the form of upload parameters in the url

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

Status code

200 OK - [GET]: The server successfully returns the data requested by the user. This operation is idempotent (Idempotent).

201 CREATED - [POST/PUT/PATCH]: The user successfully created or modified data.

202 Accepted - [*]: Indicates that a request has entered the background queue (asynchronous task)

204 NO CONTENT - [DELETE]: The user deleted the data successfully.

301: Permanent redirection

302: Temporary redirection

400 INVALID REQUEST - [POST/PUT/PATCH]: The request issued by the user has an error and the server did not proceed The operation of creating or modifying data is idempotent.

401 Unauthorized - [*]: Indicates that the user does not have permission (the token, username, and password are incorrect).

403 Forbidden - [*] Indicates that the user is authorized (as opposed to the 401 error), but access is prohibited.

404 NOT FOUND - [*]: The request issued by the user is for a record that does not exist, and the server did not perform the operation. The operation is idempotent.

406 Not Acceptable - [GET]: The format requested by the user is not available (for example, the user requested JSON format, but only XML format).

410 Gone -[GET]: The resource requested by the user is permanently deleted and will not be obtained again.

422 Unprocesable entity - [POST/PUT/PATCH] A validation error occurred while creating an object.

500 INTERNAL SERVER ERROR - [*]: A server error occurred and the user will not be able to determine whether the request made was successful.

Error handling

When the status code is 4xx, the error message should be returned, and error is used as the key.

{
    error: "Invalid API key"
}

Return results

For different operations, the results returned by the server to the user should comply with the following specifications

GET /collection: Returns a list of resource objects (Array)

GET /collection/resource: Return a single resource object

POST /collection: Return a newly generated resource object

PUT /collection/resource: Return a complete Resource object

PATCH /collection/resource: Returns a complete resource object

DELETE /collection/resource: Returns an empty document

{
    "status": 0,
    "msg": "ok",
    "results":[
        {
            "name":"肯德基(罗餐厅)",
            "location":{
                "lat":31.415354,
                "lng":121.357339
            },
            "address":"月罗路2380号",
            "province":"上海市",
            "city":"上海市",
            "area":"宝山区",
            "street_id":"339ed41ae1d6dc320a5cb37c",
            "telephone":"(021)56761006",
            "detail":1,
            "uid":"339ed41ae1d6dc320a5cb37c"
        }
        ...
        ]
}

Hypermedia API

RESTful API is best implemented as Hypermedia, that is, links are provided in the returned results to other API methods, so that users know what to do next without checking the documentation.

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

For more PHP related knowledge, please visit PHP Chinese website!

The above is the detailed content of Detailed explanation of web API interface and restful specifications. For more information, please follow other related articles on the PHP Chinese website!