使用 HTTP 方法进行RESTful服务

概况

我相信很多人目前在使用HTTP请求是大都只会用到GET、POST,GET作为READ读取数据,POST作为CREATE/UPDTE/DELETE删除数据,但其实并不仅仅是这样的,下面小编给大家介绍一下HTTP对应的一些常见谓词和在restful风格下的使用;

HTTP谓词是构成了我们“统一接口”约束的主要部分,并为我们提供了与基于名词的资源相对应的动作。主要最常见的HTTP动词是(或者正确调用的方法)是POST,GET,PUT,PATCH和DELETE。它们分别对应于create,read,update和delete(或者CURD)操作。还有许多其他动词,但使用频率较低。在那些不常用的方法中,OPTIONS和HEAD的使用频率高于其他的方法。

下面是表总结了主要HTTP方法与资源URI结合使用的建议返回值:

HTTP动词CRUD整个集合 (例如/customers)特定项目
POST CREATE 201 (Created), 'Location' header with link to /customers/{id} containing new ID. 404 (Not Found), 409 (Conflict) if resource already exists..
GET READ 200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists. 200 (OK), single customer. 404 (Not Found), if ID not found or invalid.
PUT Update/Replace 405 (Method Not Allowed), unless you want to update/replace every resource in the entire collection. 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
PATCH Update/Modify 405 (Method Not Allowed), unless you want to modify the collection itself. 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
DELETE Delete 405 (Method Not Allowed), unless you want to delete the whole collection—not often desirable. 200 (OK). 404 (Not Found), if ID not found or invalid.

POST

POST动词最常用于创建**新资源。特别是,它用于创建从属资源。也就是说,从属于其他一些(例如父)资源。换句话说,在创建新资源时,对父服务器和服务的POST负责将新资源与父资源相关联,分配ID(新资源URI)等。

成功创建后,返回HTTP状态201,返回Location标头,其中包含指向具有201 HTTP状态的新创建资源的链接。

POST既不安全也不是幂等。因此,建议用于非幂等资源请求。制作两个相同的POST请求最有可能导致两个资源包含相同的信息。

例子:

POST http://www.example.com/customers

POST http://www.example.com/customers/12345/orders

GET

HTTP GET方法用于**读取(或检索)资源的表示。在“快乐”(或非错误)路径中,GET以XML或JSON格式返回表示形式,并返回HTTP响应代码200(OK)。在错误情况下,它通常返回404(NOT FOUND)或400(BAD REQUEST)。

根据HTTP规范的设计,GET(以及HEAD)请求仅用于读取数据而不是更改它。因此,当以这种方式使用时,它们被认为是安全的。也就是说,可以调用它们而不存在数据修改或损坏的风险 - 调用它一次具有与调用它10次相同的效果,或者根本没有。此外,GET(和HEAD)是幂等的,这意味着生成多个相同的请求最终会产生与单个请求相同的结果。

不要通过GET公开不安全的操作 - 它永远不应该修改服务器上的任何资源。

例子:

GET http://www.example.com/customers/12345

GET http://www.example.com/customers/12345/orders

GET http://www.example.com/buckets/sample

PUT

PUT最常用于更新功能,与已知资源URI一起使用,请求主体包含原始资源的新更新表示。

但是,在客户端而不是服务器选择资源ID的情况下,PUT也可用于创建资源。换句话说,如果PUT是包含不存在的资源ID的值的URI。同样,请求正文包含资源表示。许多人认为这是令人费解和困惑的。因此,如果有的话,应谨慎使用这种创作方法。

或者,使用POST创建新资源并在正文表示中提供客户端定义的ID - 可能是不包含资源ID的URI(请参阅下面的POST)。

成功更新后,从PUT返回200(如果未返回正文中的任何内容,则返回204)。如果使用PUT进行创建,则在成功创建时返回HTTP状态201。响应中的主体是可选的 - 提供一个消耗更多带宽。由于客户端已经设置了资源ID,因此无需在创建案例中通过Location头返回链接。

PUT不是一个安全的操作,因为它修改(或创建)服务器上的状态,但它是幂等的。换句话说,如果您使用PUT创建或更新资源,然后再次进行相同的调用,则资源仍然存在,并且仍然具有与第一次调用时相同的状态。

例如,如果在资源上调用PUT会增加资源中的计数器,则该调用不再是幂等的。有时会发生这种情况,并且可能足以证明呼叫不是幂等的。但是,建议保持PUT请求是幂等的。强烈建议对非幂等请求使用POST。

例子:

PUT http://www.example.com/customers/12345

PUT http://www.example.com/customers/12345/orders/98765

PUT http://www.example.com/buckets/secret_stuff

PATCH

PATCH用于修改功能。PATCH请求只需要包含对资源的更改,而不是完整的资源。

这类似于PUT,但正文包含一组指令,描述如何修改当前驻留在服务器上的资源以生成新版本。这意味着PATCH主体不应该仅仅是资源的修改部分,而是某种补丁语言,如JSON Patch或XML Patch。

PATCH既不安全也不是幂等。然而,PATCH请求可以以幂等方式发布,这也有助于防止在相似时间帧内相同资源上的两个PATCH请求之间的冲突导致的不良结果。来自多个PATCH请求的冲突可能比PUT冲突更危险,因为某些补丁格式需要从已知的基点操作,否则它们将破坏资源。使用此类补丁应用程序的客户端应使用条件请求,以便在客户端上次访问资源后资源已更新时请求将失败。例如,客户端可以在PATCH请求的If-Match标头中使用强ETag。

例子:

PATCH http://www.example.com/customers/12345

PATCH http://www.example.com/customers/12345/orders/98765

PATCH http://www.example.com/buckets/secret_stuff

DELETE

DELETE很容易理解。它用于**删除由URI标识的资源。

成功删除后,返回HTTP状态200(OK)以及响应正文,可能是已删除项目的表示(通常需要太多带宽),或者包装响应(请参阅下面的返回值)。要么是返回HTTP状态204(NO CONTENT)而没有响应正文。换句话说,建议的响应是204状态,没有正文,或JSEND样式响应和HTTP状态200。

HTTP-spec-wise,DELETE操作是幂等的。如果删除资源,则会将其删除。在该资源上反复调用DELETE会导致相同的结果:资源消失了。如果调用DELETE说,递减计数器(在资源内),则DELETE调用不再是幂等的。如前所述,只要没有资源数据被更改,就可以更新使用统计和测量,同时仍然考虑服务幂等。建议使用POST进行非幂等资源请求。

但是,有一个关于DELETE idempotence的警告。第二次在资源上调用DELETE通常会返回404(NOT FOUND),因为它已被删除,因此不再可查找。根据一些观点,这使得DELETE操作不再是幂等的,但是,资源的最终状态是相同的。返回404是可以接受的,并准确地传达呼叫的状态。

例子:

DELETE http://www.example.com/customers/12345

DELETE http://www.example.com/customers/12345/orders

DELETE http://www.example.com/bucket/sample

posted @ 2019-05-22 20:00  q兽兽  阅读(2849)  评论(0编辑  收藏  举报