書名： RESTful Web API Design with Node.js 10
作者名： Valentin Bojinov
本章字數： 540字
更新時間： 2021-08-27 18:37:24

Principle 3 – Manipulate resources via standard HTTP methods

The native HTTP protocol (RFC 2616) defines eight actions, also known as HTTP verbs:

GET
POST
PUT
DELETE
HEAD
OPTIONS

TRACE
CONNECT

The first four of them just feel natural in the context of resources, especially when defining actions for data manipulation. Let's make a parallel with relative SQL databases where the native language for data manipulation is CRUD (short for Create, Read, Update, and Delete), originating from the different types of SQL statements, INSERT, SELECT, UPDATE, and DELETE, respectively. In the same manner, if you apply the REST principles correctly, the HTTP verbs should be used as shown here:

HTTP verb	Action	HTTP response status code
`GET`	Retrieves an existing resource.	`200 OK` if the resource exists, `404 Not Found` if it does not exist, and `500 Internal Server Error` for other errors.
`PUT`	Updates a resource. If the resource does not exist, the server can either decide to create it with the provided identifer or return the appropriate status code.	`200 OK` if successfully updated, `201 Created` if a new resource is created, `404 Not found` if the resource to be updated does not exist, and `500 Internal Server Error` for other unexpected errors.
`POST`	Creates a resource with an identifier generated at server side or updates a resource with an existing identifier provided from the client. If this verb is to be used only for creating but not for updating, return the appropriate status code.	`201 CREATED` if a new resource is created, `200 OK` if the resource has been updated successfully, `409 Conflict` if the resource already exists and update is not allowed, `404 Not Found` if the resource to be updated does not exist, and `500 Internal Server Error` for other errors.
`DELETE`	Deletes a resource.	`200 OK` or `204 No Content` if the resource has been deleted successfully, `404 Not Found` if the resource to be deleted does not exist, and `500 Internal Server Error` for other errors.

Note that a resource might be created by either the POST or PUT HTTP verbs, based on the policy of an application. However, if a resource has to be created under a specific URI with an identifier provided by the client, then PUT is the appropriate action:

PUT /categories/watches/model-abc HTTP/1.1
Content-Type: text/xml
Host: www.mycatalog.com

<?xml version="1.0" encoding="utf-8"?>
<Item category="watch">
    <Brand>...</Brand>
    </Price></Price>
</Item>

HTTP/1.1 201 Created 
Content-Type: text/xml 
Location: http://www.mycatalog.com/categories/watches/model-abc

However, in your application, you may want to leave it up to the backend RESTful service to decide where to expose the newly created resource, and thus create it under an appropriate but still unknown or non-existent location.

For instance, in our example, we might want the server to define the identifier of newly created items. In such cases, just use the POST verb to a URL without providing an identifier parameter. Then it is up to the service itself to provide a new unique and valid identifier for the new resource and to expose back this URL via the Location header of the response:

POST /categories/watches HTTP/1.1
Content-Type: text/xml
Host: www.mycatalog.com

<?xml version="1.0" encoding="utf-8"?>
<Item category="watch">
    <Brand>...</Brand>
    </Price></Price>
</Item>

HTTP/1.1 201 Created 
Content-Type: text/xml 
Location: http://www.mycatalog.com/categories/watches/model-abc

官术网_书友最值得收藏!

RESTful Web API Design with Node.js 10

Principle 3 – Manipulate resources via standard HTTP methods