在URL中使用与REST基本不兼容的动词?
假设我们有一些东西看起来并不是最好的资源(我们希望暂停的进程的状态,我们希望在服务器上执行的无状态计算等)。
如果在API设计中我们使用process/123/pause
或calculations/fibonacci
- 是否与REST基本上不兼容? 只要这些URL可以使用HATEOAS发现并且媒体类型是标准化的,就目前而言,从我阅读的内容来看似乎并非如此。
或者,我是否应该在这里回答行动?
注1:
我明白,可以用名词来重新说明我的一些例子。 不过,我觉得对于具体的例子,名词不能和动词一样好用。 所以我试图理解这些动词是否会立刻变得不可靠。 如果是这样,那么为什么这个建议是如此严格,以及在这些情况下我不会遵守它会带来什么好处。
笔记2:
回答“REST没有任何约束”将是一个有效的答案(这意味着这种方法是RESTful)。 回答“这取决于你问的是谁”或“这是最佳实践”并不真正回答这个问题。 这个问题假设REST的概念是一个明确定义的通用术语,两个人可以用它来指代同一组约束。 如果假设本身不正确,并且对REST的正式讨论毫无意义,请说明。
这不是严格的名词与动词; 这是关于你是否:
什么是资源? 菲尔丁如此定义它:
REST中关键的信息抽象是一种资源。 任何可以命名的信息都可以是资源:文档或图像,时间服务(例如“洛杉矶今天的天气”),其他资源的集合,非虚拟对象(例如人)等等。 换句话说,任何可能成为作者超文本引用目标的概念都必须符合资源的定义。 资源是对一组实体的概念性映射,而不是与任何特定时间点的映射对应的实体。“
现在,你的问题。 您不能只看网址并说:“这样的URL是否与REST基本上不兼容?” 因为REST系统中的URL并不重要。 根据上述定义,URLs process/123/pause
和calculations/fibonacci
标识资源更为重要。 如果他们这样做,就不会违反REST约束。 如果他们不这样做,那么你违反了REST的统一接口约束。 你的例子让我相信它不适合资源定义,因此会违反这个约束。
为了说明此系统中可能有哪些资源,您可以通过将其发布到paused-processes
资源集合来更改进程的状态。 虽然这可能是一种不寻常的使用流程的方式,但它并不与REST架构风格相悖。
在计算的情况下,计算本身可能是资源,而资源可能如下所示:
Request:
GET /calculations/5
Response:
{
fibonacci: 5,
prime-number: true,
square-root: 2.23607
}
尽管如此,这是一种不寻常的资源概念。 我想稍微更典型的用法可能如下所示:
Request:
GET /stored-calculations/12381728 (note that URL is a random identifier)
Response:
{
number: 5,
fibonacci: 5,
prime-number: true,
square-root: 2.23607
}
虽然大概你想存储关于该资源的额外信息,而不是任何人都可以用计算器完成的纯粹计算。
Response:
{
number: 5,
fibonacci: 5,
prime-number: true,
square-root: 2.23607,
last-accessed-date: 2013-10-28T00:00:00Z,
number-of-retrievals-of-this-resource: 183
}
本文有一些很好的提示:http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
从文章引用:
那些不适合CRUD操作的行为呢?
这是事情变得模糊的地方。 有很多方法:
将操作重构为显示为资源字段。 如果该操作不带参数,这将起作用。 例如,激活动作可以映射到布尔激活字段,并通过PATCH更新到资源。
将其视为具有RESTful原则的子资源。 例如,GitHub的API可让您使用PUT / gists /:id / star和unstar以DELETE / gists /:id / star的形式出现。
有时你真的无法将动作映射到合理的RESTful结构。 例如,多资源搜索对于应用于特定资源的端点没有意义。 在这种情况下,即使它不是名词,/ search也是最有意义的。 这没什么 - 只要从API消费者的角度做正确的事情,并确保它清楚记录以避免混淆。
我个人喜欢建议#2。 如果您需要暂停某些事情,您暂停了什么? 如果它是一个名字的过程,那么试试这个:
/process/{processName}/pause
在REST API中使用动词被认为是不好的做法。
SO和其他地方有一些关于为什么以及如何避免使用动词的材料。 这就是说,有很多使用动词的“REST”API。
对于你的process
API,我会让资源Process有一个state
字段,可以用PUT
修改它。
假设GET /process/$id
当前返回:
{
state: "PAUSED"
}
然后你PUT
这/process/$id
:
{
state: "RUNNING"
}
这使得过程改变状态。
在斐波那契数的情况下,只是有一个名为资源fibonacci
,并使用POST
在体内与参数(比如n表示前n个Fibonacci数),或者甚至GET
网址中的查询。
上一篇: Is using a verb in URL fundamentally incompatible with REST?