HTTP方法

RESTful API使您能够开发具有所有可能的CRUD（创建，检索，更新，删除）操作的任何类型的Web应用程序。REST指南建议对服务器的特定类型的调用使用特定的HTTP方法（虽然从技术上讲，可能违反此指南，但强烈建议不要这样做）。

使用以下给定的信息为API执行的操作查找合适的HTTP方法。

目录
HTTP GET
HTTP POST
HTTP PUT
HTTP DELETE
HTTP PATCH
摘要
词汇表

HTTP GET

使用GET请求仅检索资源表示/信息 - 而不是以任何方式修改它。由于GET请求不会更改资源的状态，因此这些是安全的方法。此外，GET API应该是幂等的，这意味着每次生成多个相同的请求必须产生相同的结果，直到另一个API（POST或PUT）更改了服务器上的资源状态。

如果Request-URI引用数据生成过程，则生成的数据应作为响应中的实体而不是过程的源文本返回，除非该文本恰好是过程的输出。

对于任何给定的HTTP GET API，如果在服务器上找到资源，那么它必须返回HTTP响应代码200 (OK)- 以及响应主体，通常是XML或JSON内容（由于它们与平台无关的性质）。

如果在服务器上找不到资源，则它必须返回HTTP响应代码404 (NOT FOUND)。类似地，如果确定GET请求本身未正确形成，则服务器将返回HTTP响应代码400 (BAD REQUEST)。

示例请求URI

HTTP POST

使用POST API 创建新的下级资源，例如，文件从属于包含它的目录，或者行从属于数据库表。严格按照REST进行讨论，POST方法用于在资源集合中创建新资源。

理想情况下，如果在源服务器上创建了资源，则响应应该是HTTP响应代码，201 (Created)并包含描述请求状态的实体，并引用新资源和Location头。

很多时候，POST方法执行的操作可能不会产生可由URI标识的资源。在这种情况下，HTTP响应代码200 (OK)或者204 (No Content)是适当的响应状态。

除非响应包含适当的Cache-Control或Expires头字段，否则对此方法的响应不可缓存。

请注意，POST 既不安全也不是幂等，并且调用两个相同的POST请求将导致两个不同的资源包含相同的信息（资源ID除外）。

示例请求URI

HTTP PUT

主要使用PUT API 来更新现有资源（如果资源不存在，则API可能决定是否创建新资源）。如果PUT API已创建新资源，则源服务器必须通过HTTP响应代码201 (Created)响应通知用户代理，如果现有资源被修改，则应该发送200 (OK)或者204 (No Content响应代码，以指示请求成功完成。

如果请求通过缓存并且Request-URI标识一个或多个当前缓存的实体，则这些条目应该被视为陈旧。对此方法的响应不可缓存。

可以在请求URI中观察POST和PUT API之间的差异。POST请求是在资源集合上发出的，而PUT请求是在单个资源上发出的。

示例请求URI

HTTP DELETE

正如名称一样，DELETE API用于删除资源（由Request-URI标识）。

code 200 (OK)如果响应包括描述状态的实体，202 (Accepted)操作是否已排队，或者204 (No Content)操作是否已执行但响应不包含实体，则DELETE请求的成功响应应该是HTTP响应。

DELETE操作是幂等的。如果删除资源，则会从资源集合中删除该资源。在该资源上反复调用DELETE API不会改变结果 - 但是第二次在资源上调用DELETE将返回404（NOT FOUND），因为它已被删除。有些人可能认为它使得DELETE方法不是幂等的。这是一个讨论和个人意见的问题。

如果请求通过缓存并且Request-URI标识一个或多个当前缓存的实体，则这些条目应该被视为陈旧。对此方法的响应不可缓存。

示例请求URI

HTTP PATCH

HTTP PATCH请求将对资源进行部分更新。如果您看到PUT请求也修改了资源实体以便更清楚 - PATCH方法是部分更新现有资源的正确选择，只有在您完全替换资源时才应使用PUT。

请注意，如果您决定在应用程序中使用PATCH API，则存在一些挑战：

  • 在浏览器，服务器和Web应用程序框架中支持PATCH并不普遍。IE8，PHP，Tomcat，Django以及许多其他软件都缺少或破坏了对它的支持。

  • 请求PATCH请求的有效载荷并不像PUT请求那样简单。例如

    HTTP GET /users/1

    产生以下回应：

    {id: 1, username: 'admin', email: 'email@example.org'}

    更新电子邮件的示例补丁请求将如下所示：

    HTTP PATCH /users/1

    [
    {“op”：“替换”，“路径”：“/ email”，“value”：“ new.email@example.org ”}
    ]

根据HTTP规范，可能存在以下可能的操作。

[ { "op": "test", "path": "/a/b/c", "value": "foo" }, { "op": "remove", "path": "/a/b/c" }, { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }, { "op": "replace", "path": "/a/b/c", "value": 42 }, { "op": "move", "from": "/a/b/c", "path": "/a/b/d" }, { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" } ]

PATCH方法不是POST或PUT方法的替代品。它应用delta（diff）而不是替换整个资源。

RESTful API的HTTP方法摘要

下表总结了上面讨论的HTTP方法的使用。

HTTP方法 CRUD 整个集合（例如/用户） 特定项目（例如/ users / 123）
POST 创建 201（已创建），'位置'标题，其中包含指向/ users / {id}的链接，其中包含新ID。 避免在单一资源上使用POST
GET 读 200（OK），用户列表。使用分页，排序和过滤来导航大列表。 200（OK），单用户。404（未找到），如果找不到ID或无效。
PUT 更新/替换 404（未找到），除非您要更新整个资源集合中的每个资源。 200（OK）或204（无内容）。如果未找到ID或无效，请使用404（未找到）。
PATCH 部分更新/修改 404（未找到），除非您想要修改集合本身。 200（OK）或204（无内容）。如果未找到ID或无效，请使用404（未找到）。
DELETE 删除 404（未找到），除非您要删除整个集合 - 请谨慎使用。 200（好的）。404（未找到），如果找不到ID或无效。

词汇表

安全方法

根据HTTP规范，GET和HEAD方法应仅用于检索资源表示 - 并且它们不会更新/删除服务器上的资源。据说这两种方法都被认为是“ 安全的 ”。

这允许用户代理以特殊方式表示其他方法，例如POST，PUT和DELETE，以便让用户意识到正在请求可能不安全的操作 - 并且他们可以更新/删除资源服务器等应该谨慎使用。

幂等方法

术语“幂等”更全面地用于描述如果执行一次或多次将产生相同结果的操作。在许多情况下，这是一个非常有用的属性，因为这意味着可以根据需要重复或重试操作，而不会导致意外的影响。对于非幂等操作，算法可能必须跟踪操作是否已经执行。

在HTTP规范中，方法GET，HEAD，PUT和DELETE被声明为幂等方法。其他方法OPTIONS和TRACE不应该有副作用，所以两者本身也是幂等的。

参考文献：

https://www.w3.org/Protocols/rfc2616/rfc2616.txt
http://tools.ietf.org/html/rfc6902
https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning