现在让我们看看 考虑使用 POST(我将在下面讨论为什么，现在请相信我的话) :

POST /v1/dogs/1/ HTTP/1.1
Host: api.animals.com


{"action":"bark"}

这个 可以可以... 但是 除非:

• {"action":"bark"}是一个文档;
• /v1/dogs/1/是一个“文档处理器”(类似于工厂) URI

我不太了解你的系统，但我敢打赌两者都不是真的:

• {"action":"bark"} 不是文件，它实际上是 就是方法你正在尝试进入 忍者神偷的服务;
• /v1/dogs/1/ URI 表示“ dog”资源(可能是具有 id==1的 dog) ，而不是文档处理器。

所以我们现在所知道的就是上面的设计并不是那么 RESTful 的，但是那到底是什么呢？有什么不好的？基本上是不好的，因为它是具有复杂含义的复杂 URI。你不能从中推断出任何东西。程序员如何知道狗有一个 bark动作，可以秘密地注入一个 POST到它？

设计问题的 API 调用

因此，让我们切入正题，试着通过考虑 在资源方面来设计这些树皮。请允许我引用 宁静的网络服务的书:

POST请求是尝试从现有的 现有资源可能是 从数据结构的角度来看，树的根是所有树的根 它的叶子节点。或者现有的资源可能是一个特殊的 “工厂” 资源的唯一目的是生成其他资源 随 POST请求一起发送的表示描述了初始 与 PUT 一样，POST请求不需要 包括一个代表。

按照上面的描述，我们可以看到，bark可以建模为 dog的子资源(因为 bark包含在一只狗中，也就是说，一声吠叫就是“吠叫”作者一只狗)。

从这个推理我们已经得到:

• 方法是 POST
• 资源是 /barks，狗的子资源: /v1/dogs/1/barks，代表 bark“工厂”。这个 URI 对于每只狗都是独一无二的(因为它在 /v1/dogs/{id}下)。

现在，您列表中的每个案例都有一个特定的行为。

# 1. 巴克只是给 dog.email发了封电子邮件，什么都没有记录。

首先，吠叫(发送电子邮件)是同步任务还是异步任务？其次，bark请求是否需要任何文档(可能是电子邮件)或者它是空的？

1.1吠声向 dog.email发送一封电子邮件，并且不记录任何东西(作为一个同步任务)

这个案子很简单。对 barks工厂资源的调用立即产生一个吠声(发送的电子邮件) ，并立即给出响应(如果确定或不确定) :

POST /v1/dogs/1/barks HTTP/1.1
Host: api.animals.com
Authorization: Basic mAUhhuE08u724bh249a2xaP=


(entity-body is empty - or, if you require a **document**, place it here)


200 OK

由于它没有记录(改变)任何东西，200 OK就足够了。它表明一切都按照预期进行。

吠叫向 dog.email发送一封电子邮件，但是没有记录任何东西(作为一个异步任务)

在这种情况下，客户机必须有跟踪 bark任务的方法。然后，bark任务应该是一个具有自己的 URI 的资源:

POST /v1/dogs/1/barks HTTP/1.1
Host: api.animals.com
Authorization: Basic mAUhhuE08u724bh249a2xaP=


{document body, if needed;
NOTE: when possible, the response SHOULD contain a short hypertext note with a hyperlink
to the newly created resource (bark) URI, the same returned in the Location header
(also notice that, for the 202 status code, the Location header meaning is not
standardized, thus the importance of a hipertext/hyperlink response)}


202 Accepted
Location: http://api.animals.com/v1/dogs/1/barks/a65h44

这样，每个 bark都是可追踪的。然后，客户机可以向 bark URI 发出 GET，以了解它的当前状态。甚至可以用 DELETE来取消。

树皮向 dog.email发送一封电子邮件，然后将 dog.barkCount增加1

如果你想让客户知道 dog资源发生了变化，这个问题可能更棘手:

POST /v1/dogs/1/barks HTTP/1.1
Host: api.animals.com
Authorization: Basic mAUhhuE08u724bh249a2xaP=


{document body, if needed; when possible, containing a hipertext/hyperlink with the address
in the Location header -- says the standard}


303 See Other
Location: http://api.animals.com/v1/dogs/1

在这种情况下，location头的意图是让客户机知道他应该查看 dog。来自 关于 303的 HTTP RFC:

此方法的存在主要是为了允许 POST-激活的脚本 将用户代理重定向到选定的资源。

如果任务是异步的，那么就需要一个 bark子资源，就像 1.2的情况一样，当任务完成时，应该在 GET .../barks/Y返回 303。

3. 树皮产生一个新的“ bark”记录，当树皮发生时 bark.timestamp记录。它也增加 dog.barkCount1。

POST /v1/dogs/1/barks HTTP/1.1
Host: api.animals.com
Authorization: Basic mAUhhuE08u724bh249a2xaP=


(document body, if needed)


201 Created
Location: http://api.animals.com/v1/dogs/1/barks/a65h44

在这里，由于请求而创建了 bark，因此应用了状态 201 Created。

如果创建是异步的，则需要使用 202 Accepted(正如 HTTP RFC 所说)。

保存的时间戳是 bark资源的一部分，可以用 GET检索它。更新的狗可以“记录”在该 GET dogs/X/barks/Y以及。

4.巴克运行一个系统命令从 Github 下载最新版本的狗代码。然后向 dog.owner发送一条短信，告诉他们新的狗代码正在生产中。

这篇文章的措辞很复杂，但它基本上是一个简单的异步任务:

POST /v1/dogs/1/barks HTTP/1.1
Host: api.animals.com
Authorization: Basic mAUhhuE08u724bh249a2xaP=


(document body, if needed)


202 Accepted
Location: http://api.animals.com/v1/dogs/1/barks/a65h44

然后，客户机将向 /v1/dogs/1/barks/a65h44发出 GET，以了解当前的状态(如果提取了代码，则将电子邮件发送给所有者等)。每当狗改变，一个 303是适用的。

收工

引用 Roy Fielding:

REST 对方法的唯一要求是它们是一致的 为所有资源定义(例如，这样中介体就不必 了解资源类型，以便理解 要求)。

在上面的例子中，POST是统一设计的。它会使狗“ bark”。这是不安全的(意味着树皮对资源有影响) ，也不是幂等的(每个请求产生一个新的 bark) ，这很适合 POST动词。

程序员应该知道: 从 POST到 barks产生 bark。响应状态代码(必要时还带有实体主体和头部)负责解释发生了什么变化以及客户机可以和应该如何进行。

_{注: 使用的主要来源是: “ 宁静的网络服务”书，HTTP RFC和 Roy Fielding 的博客。}

编辑:

这个问题和答案自从它们第一次被创建以来已经发生了很大的变化。原始问题询问 URI 的设计如下:

ACTION http://api.animals.com/v1/dogs/1/?action=bark

下面是为什么这不是一个好的选择的解释:

客户机如何告诉服务器 怎么办与数据是 方法资料。

• RESTful Web 服务在 HTTP 方法中传递方法信息。
• 典型的 RPC 样式和 SOAP 服务将它们的服务保存在实体体和 HTTP 头中。

数据[客户机希望服务器]操作的部分 是 范围界定信息。

• RESTful 服务使用 URI.SOAP/RPC-Style 服务再次使用实体体和 HTTP 头。

以 Google 的 URI http://www.google.com/search?q=DOG为例，这里的方法信息是 GET，范围信息是 /search?q=DOG。

长话短说:

• 在 RESTful 体系结构中，方法信息进入 HTTP 方法。
• 在 面向资源的体系结构中，范围信息进入 URI。

根据经验法则:

如果 HTTP 方法不匹配方法信息，服务就不是 RESTful 的。如果范围界定信息不在 URI 中，则服务不是面向资源的。

您可以将 “吠叫”“开拍”放在 URL (或实体主体)中并使用 POST。没有问题，它工作，并可能是最简单的方式做到这一点，但这不是 RESTful。

为了使您的服务真正 RESTful，您可能需要后退一步，考虑您真正想在这里做什么(它将对资源产生什么影响)。

我不能谈论您的具体业务需求，但是让我给您举一个例子: 考虑一个 RESTful 订购服务，其中订单位于像 example.com/order/123这样的 URI。

现在假设我们要取消订单，我们该怎么做呢？人们可能会认为这是一个 “取消” “开拍”和设计它作为 POST example.com/order/123?do=cancel。

这不是 RESTful，正如我们上面所说的。相反，我们可以使用 PUT作为 order的一个新表示，并将一个 canceled元素发送给 true:

PUT /order/123 HTTP/1.1
Content-Type: application/xml


<order id="123">
<customer id="89987">...</customer>
<canceled>true</canceled>
...
</order>

就是这样。如果订单不能被取消，可以返回一个特定的状态码

在您的特定场景中，您可以尝试类似的东西。这样，当一只狗在叫的时候，例如，/v1/dogs/1/的 GET可以包含 ^{(例如 <barking>true</barking>)}的信息。或者... 如果这太复杂，放松您的 REST 需求，坚持使用 POST。

更新:

我不想把答案说得太大，但是要掌握将算法(开拍)作为一组资源公开的窍门还需要一段时间。与其从动作的角度思考(“在地图上搜索地点”) ，不如从动作的结果来思考(< em > “地图上与搜索匹配的地点列表 准则」

如果您发现自己的设计不适合 HTTP 的统一接口，那么您可能会回到这一步。

查询变量 是 范围界定信息，但是 没有表示新的资源(/post?lang=en显然是 一样资源的 /post?lang=jp，只是不同的表示)。相反，它们用于将 /post?lang=jp0(如 ?page=10，因此该状态不保存在服务器中; 这里的 ?lang=en也是一个例子)或 /post?lang=jp1传递给 /post?lang=jp2(/search?q=dogs，/dogs?code=1)。再说一次，不是特定的资源。

HTTP 谓词的(方法)属性:

显示 URI 中的 ?action=something不是 RESTful 的另一个明确点是 HTTP 动词的属性:

• GET和 HEAD是安全的(并且是幂等的) ;
• PUT和 DELETE仅是幂等的;
• POST两者都不是。

安全 : GET或 HEAD请求是对 读某些数据的请求，而不是更改任何服务器状态的请求。客户端可以发出 GET或 HEAD请求10次，这与发出一次或 从来没有成功过请求是相同的。

幂等性 : 一个幂等运算，无论你应用它一次还是多次，它都有相同的效果(在数学中，乘以零是幂等的)。如果您只删除一次 DELETE资源，那么再次删除也会产生同样的效果(资源已经是 GONE了)。

^{_{POST既不安全也不幂等。对一个“工厂”资源发出两个相同的 POST请求可能会导致两个包含相同的从属资源 信息。如果重载(URI 或实体体中的方法) POST，那么所有的赌注都没有了。}}

这两个属性对于 HTTP 协议的成功(在不可靠的网络上)都很重要: 你有多少次更新(GET)的网页没有等待，直到它完全加载？

创建一个 开拍并将其放在 URL 中显然违反了 HTTP 方法的约定。再一次，技术允许你，你可以做到这一点，但这不是 RESTful 设计。