004-REST-使用 HTTP 方法进行 RESTful 服务

布满荆棘的人生 2022-01-21 08:29 279阅读 0赞

HTTP 谓词构成了我们“统一接口”约束的主要部分，并为我们提供了与基于名词的资源相对应的动作。 主要或最常用的 HTTP 谓词（或正确调用的方法）是 POST，GET，PUT，PATCH和DELETE。 它们分别对应于创建，读取，更新和删除（或CRUD）操作。 还有许多其他动词，但使用频率较低。 在那些不常用的方法中，OPTIONS 和 HEAD 的使用频率高于其他方法。

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

<table> 
 <thead> 
  <tr> 
   <th>HTTP 动词</th> 
   <th>CRUD</th> 
   <th>整个集合(e.g. /customers)</th> 
   <th>特定 item(e.g./customers/{id})</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>POST</td> 
   <td>Create</td> 
   <td>201(已创建)，‘Location’ header，其中包含指向/customers/{id}的链接，其中包含新 ID</td> 
   <td>404(未找到)，409(冲突)，如果资源已存在</td> 
  </tr> 
  <tr> 
   <td>GET</td> 
   <td>Read</td> 
   <td>200(OK),客户列表。使用分页，排序和过滤来导航大列表</td> 
   <td>200(OK),单个客户。404(未找到)，如果找不到ID或无效</td> 
  </tr> 
  <tr> 
   <td>PUT</td> 
   <td>Update/Replace</td> 
   <td>405(方法不允许)，除非你要更新/替换整个集合中的每个资源</td> 
   <td>200(OK),或204(无内容)，404(未找到)，如果找不大ID或无效</td> 
  </tr> 
  <tr> 
   <td>PATCH</td> 
   <td>Update/Modify</td> 
   <td>405(方法不允许)，除非你想要修改集合本身</td> 
   <td>200(OK)，或204(无内容)，404(未找到)，如果找不到ID或无效</td> 
  </tr> 
  <tr> 
   <td>DELETE</td> 
   <td>Delete</td> 
   <td>405(方法不允许)，除非你想删除整个集合-通常不需要</td> 
   <td>200(OK)，404(为找到)，如果找不到ID或无效</td> 
  </tr> 
 </tbody> 
</table>

### POST ###

POST 动词最常用于创建**新资源。特别是，它用于创建从属资源。也就是说，从属于其他一些(eg. parent)资源。换句话说，在创建新资源时，对父服务器和服务的 POST 负责将新资源与父资源相关联，分配 ID(新资源URI)等。
        
        成功创建后，返回 HTTP 状态 201，返回 Location header，其中包含指向具有 201 HTTP 状态的新创建资源的链接。
        
        POST 即不安全也不是幂等。因此，建议用于非幂等资源请求。制作两个相同的 POST 请求最有可能导致两个资源包含相同的信息。
    示例：
        - POST http://www.example.com/customers
        - POST http://www.example.com/customers/12345/orders

### GET ###

HTTP GET 方法用于**读取(或检索)资源的表示。在”happy“(或非错误)路径中，GET 以 XML 或 JSON 格式返回表示形式，并返回 HTTP 响应代码200(OK)。在错误情况下，它通常返回 404 或 400。
        
        根据 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。同样，请求体包含资源表示。许多人认为这是令人费解和困惑的。因此，如果有的话，应谨慎使用这种创作方法。
        
        成功更新后，从 PUT 返回 200(如果未返回正文中的任何内容，则返回 204)。如果使用 PUT 进行创建，则在成功创建时返回 HTTP 状态 201.响应中的主体是可选的-提供一个小号更多带宽。由于客户端已经设置了资源ID，因此无需在创建案例中通过 Location header 返回链接。
        
        PUT 不是一个安全的操作，因为它修改(或创建)服务器上的状态，但他是幂等的。换句话说，如果你使用 PUT 创建或更新资源，然后再次进行相同的调用，则资源仍然存在，并且仍让具有与第一次调用时相同的状态。
        
        例如，如果在资源上调用 PUT 会增加资源中的计数器，则该调用不再是幂等的。有时会发生这种情况，并且可能足以证明呼叫不是幂等的。但是，建议保持 PUT 请求是幂等的。强烈建议对非幂等请求使用 POST。
        
    示例：
        - PUT http://www.example.com/customers/12345
        - PUT http://www.example.com/customers/12345/orders/98756
        - PUT http://www.example.com/buckets/secret_stuff

### PATCH ###

PATCH 用于”修改“功能。PATCH 请求只需要包含对资源的更改，而不是完整的哀怨。
        
        这类似于 PUT，但正文包含一组指令，描述如何修改当前驻留在服务器上的资源以生成新版本。这意味着 PATCH 主体不应该仅仅是资源的修改部分，而是某种 PATCH 语言，如 JSON Patch 或 XML Patch。
        
        PATCH 既不安全又不幂等。然而，PATCH 如何可以以幂等方式发布，这也有助于防止在相似时间帧内相同资源上的两个 PATCH 请求之间的冲突导致的不良结果。来自多个 PATCH 请求的冲突可能比 PUT 冲突更危险，因为某些 PATCH 格式需要从一直的基点操作，否则他们将破坏资源。使用此类 PATCH 应用程序的客户端使用条件请求，以便在客户端上次访问资源后资源已更新时请求将失败。例如，客户端可以在 PATCH 请求的 If-Match header 中使用强 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是可以接受的，并准确地传达呼叫的状态。