如何创建没有动词的REST URL？

Question

我正在努力确定如何设计restful URL.我全都是为了使用带名词的URL的安静方法,而不是动词不明白如何做到这一点.

我们正在创建一个实施金融计算器的服务.计算器需要一堆参数,我们将通过CSV文件上传.用例包括:

1. 上传新参数
2. 获取最新参数
3. 获取给定营业日期的参数
4. 使一组参数处于活动状态
5. 验证一组参数

我收集的其余方法是拥有以下类型的URL:

/parameters
/parameters/12-23-2009

您可以通过以下方式实现前三个用例:

1. 在post请求中包含参数文件的POST
2. GET的第一个URL
3. 获取第二个URL

但是,如果没有动词,你如何做第4和第5个用例？你不需要像以下网址:

/parameters/ID/activate
/parameters/ID/validate

??

Answer 1

良好URI设计的一般原则:

• 不要使用查询参数来改变状态
• 如果你能提供帮助,请不要使用混合案例路径; 小写是最好的
• 不要在URI中使用特定于实现的扩展名(.php,.py,.pl等)
• 不要使用您的URI 进入RPC
• 不要限制你的URI的空间尽可能地
• 请保持路径段短
• 难道不是选/resource或/resource/; 从您不使用的重定向创建301重定向
• 做一个资源的子选择使用查询参数; 即分页,搜索查询
• 别动东西了URI的,应该是在HTTP报头或身体

(注意:我没有说"RESTful URI设计"; REST在REST中基本上是不透明的.)

HTTP方法选择的一般原则:

• 不要使用GET改变状态; 这是让Googlebot破坏你的一天的好方法
• 除非您要更新整个资源,否则请勿使用PUT
• 除非您也可以在同一URI上合法地执行GET,否则不要使用PUT
• 不要使用POST来检索长期存在或可能合理缓存的信息
• 不要执行PUT 不是幂等的操作
• 请使用GET为尽可能
• 不要使用POST优先有疑问时放
• 不要使用POST时,你必须做一些事情,感觉RPC样
• 不要使用PUT对资源类,较大或分层
• 请优先使用DELETE来删除资源
• 请使用GET的东西像计算,除非你的投入很大,在这种情况下使用POST

使用HTTP进行Web服务设计的一般原则:

• 不要将元数据放在应该位于标题中的响应主体中
• 不要将元数据放在单独的资源中,除非包含它会产生大量开销
• 请使用适当的状态代码
  • 201 Created创建资源后; 资源必须在发送响应时存在
  • 202 Accepted 成功执行操作或异步创建资源后
  • 400 Bad Request当某人对明显虚假的数据进行操作时; 对于您的应用程序,这可能是一个验证错误; 通常为未捕获的例外保留500
  • 401 Unauthorized当有人访问您的API时,如果没有提供必要的Authorization标题,或者其中的凭据Authorization无效; 如果您不希望通过Authorization标头获取凭据,请不要使用此响应代码.
  • 403 Forbidden 当某人以可能是恶意的方式或未经授权的方式访问您的API时
  • 405 Method Not Allowed 当有人使用POST时他们应该使用PUT等
  • 413 Request Entity Too Large 当有人试图向您发送一个不可接受的大文件
  • 418 I'm a teapot 当试图用茶壶煮咖啡时
• 不要使用缓存头时,您可以
  • ETag 当您可以轻松地将资源减少为哈希值时,标头很好
  • Last-Modified 应该告诉你,保持资源更新时间的时间戳是一个好主意
  • Cache-Control并Expires应给予明智的价值
• 尽一切可能尊重请求中的缓存标头(If-None-Modified,If-Modified-Since)
• 难道当他们使用感重定向,但这些应该是罕见的Web服务

关于您的具体问题,POST应该用于#4和#5.这些操作属于上述"类RPC"指南.对于#5,请记住POST不一定要使用Content-Type: application/x-www-form-urlencoded.这可以很容易地成为JSON或CSV有效负载.

Answer 2

也许是这样的:

PUT /parameters/activation HTTP/1.1
Content-Type: application/json; encoding=UTF-8
Content-Length: 18

{ "active": true }

Answer 3

每当看起来你需要一个新动词时,请考虑将该动词转换为名词.例如,将"激活"变为"激活",将"验证"变为"验证".

但就你所写的内容而言,我说你的应用程序有更大的问题.

每当提出一个名为"参数"的资源时,它应该在每个项目团队成员的脑海中发出红色标记.'参数'可以逐字地应用于任何资源; 它不够具体.

"参数"究竟代表什么？可能有许多不同的东西,每个东西都应该有一个独立的资源专用于它.

另一种解决方法 - 当您与最终用户(可能对编程知之甚少的人)讨论您的应用程序时,他们自己反复使用的单词是什么？

这些是您应该设计应用程序的词语.

如果您尚未与潜在用户进行此转换 - 请立即停止所有操作,并且在您执行此操作之前不要编写另一行代码!只有这样,您的团队才能了解需要构建的内容.

我对财务软件一无所知,但如果我不得不猜测,我会说一些资源可能会出现在"报告","付款","转账"和"货币"等名称上.

软件设计过程的这一部分有很多好书.我可以推荐的两个是域驱动设计和分析模式.

Answer 4

您的网址设计与您的应用程序是否为REST是无关的.因此,短语"RESTful URLS"是无意义的.

我认为你应该更多地阅读REST实际上是什么.REST将URL视为不透明,因此不知道它们中的内容,无论是动词还是名词或其他什么.您可能仍希望设计URL,但这是关于UI而不是REST.

也就是说,让我们回答你的问题:最后两个案例不是RESTful,并且不适合任何类型的宁静方案.这些就是你所谓的RPC.如果您对REST非常认真,那么您必须重新思考应用程序的工作原理.要么,要么放弃REST,只需将您的应用作为RPC应用程序.

可能不是.

这里的想法是你必须将所有东西视为一种资源,所以一旦一组参数有一个你可以引用它的URL,你只需添加

得到[parametersurl]/validationresults

发表[paramatersurl]

body:{command:"activate"}

但同样,激活的东西是RPC,而不是REST.

Answer 5

激活和验证要求是您尝试更改资源状态的情况.将订单"完成"或其他一些请求"提交"也没有什么不同.有许多方法可以对这些类型的状态更改进行建模,但我发现通常可以使用的方法是为同一状态的资源创建集合资源,然后在集合之间移动资源以影响状态.

例如,创建一些资源,如,

/ActiveParameters
/ValidatedParameters

如果要激活一组参数,请将该集添加到ActiveParameters集合中.您可以将参数集作为实体主体传递,也可以将URL作为查询参数传递,如下所示:

POST /ActiveParameters?parameter=/Parameters/{Id}

使用/ ValidatedParameters可以完成同样的事情.如果参数无效,则服务器可以向请求返回"错误请求",以将参数添加到已验证参数的集合中.