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-ControlExpires头字段,否则对此方法的响应不可缓存

请注意,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