structure REST API when , The first step to take is to determine API Resources to be managed . These resources are usually described as plural nouns , Such as customers 、events 、 or transactions . stay Web When different resources are identified in the service , You will build a list of nouns , Used to describe how users can API Different data managed in .
When doing this , Be sure to consider any nested resources . for example ,customers May have guests or sales May contain events . In defining API Interface , It would be helpful to establish these resource hierarchies .
determine Web After the resources in the service , You need to use these resources to define API Interface . Here are some of the services you may be using for payment processing API Some sample interfaces for resources found in ：transactions
GET/transactions Get transaction list .GET/transactions/<transaction_id> Get single transaction .POST/transactions Create a new transaction .PUT/transactions/<transaction_id> Update transaction .PATCH/transactions/<transaction_id> Partial update transactions .DELETE/transactions/<transaction_id> Delete transaction . These six nodes cover Web In service transactions establish 、 Read 、 All actions required to update and delete .Web Each resource in the service will have a similar node list , Depending on what users can use API Actions performed .
Be careful ： Nodes should not contain predicates . contrary , You should choose the appropriate HTTP Method to communicate the operation of the endpoint . for example , The following endpoint contains an unneeded predicate ：
GET /getTransactions
here ,get It does not need to be included in the interface .HTTP Method has provided semantic meaning to the endpoint by indicating the operation . You can delete... From the interface ：GET
GET /transactions
This interface contains only one plural noun ,HTTP GET Methods communicate actions .
Now let's take a look at the interface example of nested resources . ad locum , You will see guests Nested in resources events The next interface ：
GET/events/<event_id>/guests Get guest list .GET/events/<event_id>/guests/<guest_id> Get a single guest .POST/events/<event_id>/guests Create a new guest .PUT/events/<event_id>/guests/<guest_id> Update guests .PATCH/events/<event_id>/guests/<guest_id> Partially updated guests .DELETE/events/<event_id>/guests/<guest_id> Delete guest . Use these interfaces , Can manage specific events in the system .guests
This is not the only way to define interfaces for nested resources . Some people prefer to use query strings to access nested resources . The query string allows you to follow HTTP Request to send other parameters together . In the following interfaces , Append query string guests To get specific information event_id：
GET /guests?event_id=23
This node guests Any unreferenced given... Will be filtered out event_id . And API Many things in design are the same , You need to decide which method is best for your Web service .
Be careful ： REST API It's unlikely to be here Web The service remains unchanged throughout its lifecycle . Resources will change , You need to update the interface node to reflect these changes . This is it. API Version control place .API Version control allows you to modify API, Without worrying about breaking existing integrations .
There are various version control strategies . Choosing the right option depends on API The requirements of . Here are some of the most popular API Version control options ：
Whatever strategy you choose , Yes API Versioning is an important step to ensure that it can adapt to changing needs and support existing users .
For formatting Web Two common options for service data are XML and JSON. Traditionally ,XML stay [SOAP] API It's very popular in , but JSON stay REST API More popular in China . To compare the two , Look at a format that is XML and JSON Sample resources for book.
Here is a Book formatted as XML The book of ：
<?xml version="1.0" encoding="UTF-8" ?>
<book>
<title>Python Basics</title>
<page_count>635</page_count>
<pub_date>2021-03-16</pub_date>
<authors>
<author>
<name>David Amos</name>
</author>
<author>
<name>Joanna Jablonski</name>
</author>
<author>
<name>Dan Bader</name>
</author>
<author>
<name>Fletcher Heisler</name>
</author>
</authors>
<isbn13>978-1775093329</isbn13>
<genre>Education</genre>
</book>
XML Use a series of Elements Code the data . Each element has a start and end tag , The data is somewhere in between . Elements can be nested in other elements . You can see this above , Several of these tags are nested in .<author>``<authors>
Now? , have a look JSON Same as in ：book
{
"title": "Python Basics",
"page_count": 635,
"pub_date": "2021-03-16",
"authors": [
{
"name": "David Amos"},
{
"name": "Joanna Jablonski"},
{
"name": "Dan Bader"},
{
"name": "Fletcher Heisler"}
],
"isbn13": "978-1775093329",
"genre": "Education"
}
JSON Store data in something like Python Dictionary key value alignment . And XML equally ,JSON Support for nesting data to any level , So you can model complex data .
JSON and XML In essence, it is no better than the other , but REST API Developers prefer JSON. When
You will REST API And React or Vue When the front-end frame is paired , Especially so .
After selecting the data format , The next step is to determine how to respond HTTP request . come from REST API All responses to should have a similar format , And include the correct HTTP The status code .
In this section , You will view management cars detailed list Assumptions API Some examples of HTTP Respond to . These examples will show you how to set up API Format of response . For the sake of clarity , You will see the original HTTP Requests and responses , Instead of using something like .requests
To start , Please check out GET Yes /cars Request , Where the following list is returned ：
GET /cars HTTP/1.1
Host: api.example.com
this HTTP The request consists of four parts ：
GET yes HTTP Method type ./cars yes API Interface .HTTP/1.1 yes HTTP edition . host ：api.example.com yes API host . These four parts are your contribution to /cars send out GET Request everything you need . Now let's look at the response . this API Use JSON As a data exchange format ：
HTTP/1.1 200 OK
Content-Type: application/json
...
[
{
"id": 1,
"make": "GMC",
"model": "1500 Club Coupe",
"year": 1998,
"vin": "1D7RV1GTXAS806941",
"color": "Red"
},
{
"id": 2,
"make": "Lamborghini",
"model":"Gallardo",
"year":2006,
"vin":"JN1BY1PR0FM736887",
"color":"Mauve"
},
{
"id": 3,
"make": "Chevrolet",
"model":"Monte Carlo",
"year":1996,
"vin":"1G4HP54K714224234",
"color":"Violet"
}
]
The API Return a response , It includes cars A list of . You know that due to the status code 200 OK Why , Response successful . The header of the response Content-Type Also set to application/json . This tells the user to parse the response into JSON.
Be careful ： When you use real API when , You will see more HTTP header . These headers are in API There's a difference between , So they have been excluded from these examples .
Be sure to always set the correct header on the response Content-Type. If sent JSON,Content-Type Is set to application/json . If XML, Set it to application/xml. This header tells the user how to analyze the data .
You also want to include the appropriate status code in the response . For any successful request ,GET Should return 200 OK . This tells the user that their request has been processed as expected .
Let's look at the other one GET request , This time it's a car ：
GET /cars/1 HTTP/1.1
Host: api.example.com
this HTTP Request to inquire about cars 1 Of API. Here is the response ：
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1,
"make": "GMC",
"model": "1500 Club Coupe",
"year": 1998,
"vin": "1D7RV1GTXAS806941",
"color": "Red"
},
This response contains a single... With vehicle data JSON object . Because it is a single object , So you don't need to wrap it in a list . Same as the previous response , There is also a status code .200 OK
Be careful ： Requests should never modify existing resources . If the request contains data , This data should be ignored , also API Unchanged resource should be returned .GET
Next , View the request to add a new car ：POST
POST /cars HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"make": "Nissan",
"model": "240SX",
"year": 1994,
"vin": "1N6AD0CU5AC961553",
"color": "Violet"
}
this POST Request to include the new vehicle in the request JSON. It will header Content-Type Set to application/json In order to API Know the content type of the request .API Will be taken from JSON Create a new car .
Here is the response ：
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": 4,
"make": "Nissan",
"model": "240SX",
"year": 1994,
"vin": "1N6AD0CU5AC961553",
"color": "Violet"
}
This response has a status code 200 OK,201 Created Used to inform the user that a new resource has been created .201 Created Make sure to use... For all successful requests instead of POST .
This response also includes a copy of the new vehicle id, It consists of API Generated id Please be sure to send back... In the response a, So that the user can modify the resource again .
Be careful ： When users use POST or PUT or PATCH When modifying resources , It is important to always send back a copy of the resource . such , Users can see the changes they have made .
Now look at the request ：PUT
PUT /cars/4 HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"make": "Buick",
"model": "Lucerne",
"year": 2006,
"vin": "4T1BF3EK8AU335094",
"color":"Maroon"
}
This request uses... From the previous request id Use PUT All new data update cars . As a reminder , Please update all fields on the resource with the new data . Here is the response ：
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 4,
"make": "Buick",
"model": "Lucerne",
"year": 2006,
"vin": "4T1BF3EK8AU335094",
"color":"Maroon"
}
The response includes... With new data car Copy of . Again , You always want PUT Send back the requested full resource . This also applies to PATCH request ：
PATCH /cars/4 HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"vin": "VNKKTUD32FA050307",
"color": "Green"
}
PATCH Request to update only a portion of the resource . In the above request ,vin and color The field will be updated with the new value . Here is the response ：
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 4,
"make": "Buick",
"model": "Lucerne",
"year": 2006,
"vin": "VNKKTUD32FA050307",
"color": "Green"
}
Response includes car A complete copy of . As you can see , Only vin and color Field updated .
Last , have a look REST API Upon receipt of DELETE How to respond to a request . The following is to delete ：
HTTP/1.1 204 No Content
This response includes only the status code . This status code 204 No Content Tell the user that the operation is successful , But nothing is returned in the response . It makes sense , because car have been deleted . There is no reason to send a copy back in the response .
Yes REST API It is always possible for a request to fail . It is best to define the appearance of the error response . These responses should include a description of the error and the corresponding status code . In this section , You will look at a few examples .
First , Please check the API Requests for resources that do not exist in ：
GET /motorcycles HTTP/1.1
Host: api.example.com
here , The user to /motorcycles Send a nonexistent request .API The following response will be sent back ：
HTTP/1.1 404 Not Found
Content-Type: application/json
...
{
"error": "The requested resource was not found."
}
This response includes a status code . besides , The response also contains a... With a descriptive error message JSON object . Providing a descriptive error message provides the user with more context about the error .
Now look at the error response when the user sends an invalid request ：
POST /cars HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"make": "Nissan",
"year": 1994,
"color": "Violet"
this POST Request includes JSON, But the format is incorrect . It is missing the closing brace at the end （}）.API This data will not be processed . The error response will inform the user of the following problems ：
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "This request was not properly formatted. Please send again."
}
This response includes a descriptive error message and a status code , Inform the user that they need to repair the request .
There are several other ways , Even if the request is in the correct format , It could be wrong . In the next example , User sends request , But it contains unsupported media types ：POST
POST /cars HTTP/1.1
Host: api.example.com
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" ?>
<car>
<make>Nissan</make>
<model>240SX</model>
<year>1994</year>
<vin>1N6AD0CU5AC961553</vin>
<color>Violet</color>
</car>
In this request , The user sends XML, but API Support only JSON. The API The response method of is as follows ：
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json
{
"error": "The application/xml mediatype is not supported."
}
This response includes a status code , To indicate that the request contains API Unsupported data format . This error code is meaningful for malformed data , But even if the format is correct, the data is invalid ？
In the next example , User sends request , But the contained data does not match the fields of other data ：
POST /cars HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"make": "Nissan",
"model": "240SX",
"topSpeed": 120
"warrantyLength": 10
}
In this request , The user to JSON add to topSpeed and warrantyLength Field .API These fields are not supported , So it will respond with an error message ：
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"error": "Request had invalid or missing data."
}
This response includes a status code . This status code indicates that there is no problem with the request , But the data is invalid .REST API The incoming data needs to be verified . If the user sends data with the request , be API The data should be validated and the user notified of any errors .
Response request （ Whether successful or wrong ） yes REST API One of the most important jobs . If your API Intuitive and accurate response , It will be easier for users to surround your Web Services build applications . Fortunately, , Some excellent Python Web The framework abstracts the process HTTP The complexity of the request and the return response .
