我挣扎,以确定如何设计宁静的URL。 我所有的使用有名词和动词没有网址,不知道如何做到这一点的RESTful方法。
我们正在创造一个服务来实现金融计算器。 计算器需要一堆,我们将通过一个CSV文件上传参数。 用例将包括:
- 上传新的参数
- 获取最新参数
- 获取给定的业务日期参数
- 做一组活动参数
- 验证一组参数
我收集了宁静的做法是有以下类型的网址:
/parameters
/parameters/12-23-2009
你可以达到前三个用例:
- 帖子里您在POST请求的参数文件
- GET第一URL
- GET第二网址
但是,你怎么办4楼和5使用的情况下没有一个动词? 难道你需要这样的网址:
/parameters/ID/activate
/parameters/ID/validate
??
Answer 1:
也许是这样的:
PUT /parameters/activation HTTP/1.1
Content-Type: application/json; encoding=UTF-8
Content-Length: 18
{ "active": true }
Answer 2:
良好的URI设计通则:
- 不要使用查询参数来改变状态
- 不要使用大小写混合的路径,如果你能帮助它; 小写是最好的
- 不要在你的URI使用特定于实现的扩展名(.php,的.py,特等等)
- 不要陷入RPC与你的URI
- 不要限制你的URI的空间尽可能地
- 请保持路径段短
- 难道不是选
/resource
或/resource/
; 从您不使用一个创建301个重定向 - 做一个资源的子选择使用查询参数; 即分页,搜索查询
- 别动东西了URI的,应该是在HTTP报头或身体
(注:我并没有说“REST风格的URI的设计”; URI是在REST基本上是不透明的。)
对于HTTP方法的选择一般原则:
- 永远不要使用GET改变状态; 这是有Googlebot的毁了你一天的好方法
- 除非你正在更新整个资源不要使用PUT
- 不要使用PUT,除非你也可以合法地做同样的URI GET
- 不要使用POST来检索长寿命或可能是合理的缓存信息
- 不执行不操作幂等与PUT
- 请使用GET为尽可能
- 不要使用POST优先有疑问时放
- 不要使用POST时,你必须做一些事情,感觉RPC样
- 不要使用PUT对资源类,较大或分层
- 不要使用优先删除张贴到移除资源
- 请使用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 3:
每当它看起来像你需要一个新的动词,想想转向该动词变成名词代替。 例如,转“激活”变成“激活”,和“验证”变成“验证”。
但是,仅仅从你写什么,我会说你的应用有更大的问题。
提出了一种被称为“参数”资源的任何时间,应该在每个项目团队成员的脑海发送了红旗。 “参数”简直可以适用于任何资源; 这是不够具体。
这到底是一个“参数”代表什么? 也许一些不同的东西,每一个都应该有专门给它一个独立的资源。
在这另一种方式来获得 - 当你讨论与最终用户(那些谁可能不太了解编程)什么是他们自己反复使用的话你的应用程序?
这些都是你应该围绕设计应用程序的话。
如果你还没有过这样的转换与潜在用户 - 马上停止一切不写另一行代码,直到你做! 只有这样,你的团队有需要建立什么样的想法。
我一无所知财务软件,但如果要我猜,我会说一些资源可以通过名称,如“报告”,“付款”,“转让”和“货币”去了。
有对软件设计过程中,这部分的一些好书。 二,我可以推荐的领域驱动设计和分析模式 。
Answer 4:
您的网址的设计无关,与你的应用程序是基于REST与否。 因此,短语“rest风格的url”是无稽之谈。
我认为你应该做什么REST实际上是一些更多的阅读。 REST把网址为不透明的,因此不知道什么是在他们,是否孤单动词或名词或什么的。 你可能还是想设计自己的网址,但仅此UI,而不是休息。
这就是说,让我们对你的问题:最后两种情况都是不平安,不适合任何一种宁静的方案。 这些都是可以称之为RPC。 如果你认真REST你必须重新考虑你的应用程序从底层是如何工作的。 要么,放弃REST,只是做你的应用程序作为一个RPC应用程序。
Hrmmm也许不是。
这里的想法是,你要像对待一切作为一种资源,所以一旦一组参数有你可以参考从它一个网址,你只需要添加
得到[parametersurl] / validationresults
信息[paramatersurl]
体:{命令: “激活”}
但同样,激活的是RPC,而不是REST。
Answer 5:
在激活和验证的要求是,你正试图改变资源的状态的情况。 这是没有什么不同的是作出命令,“已完成”或“提交”一些其他的要求。 有许多方法对这些类型的状态变化,但一个的,我发现,经常的工作原理是在相同状态下的资源创建馆藏资源,然后移动收集之间的资源来影响状态模型。
例如,创建一些资源,例如,
/ActiveParameters
/ValidatedParameters
如果你想使一组活动参数,然后再添加一组到ActiveParameters集合。 您既可以通过这组参数作为一个实体机构,或者你可以通过一个URL作为查询参数,如下所示:
POST /ActiveParameters?parameter=/Parameters/{Id}
同样的事情可以用/ ValidatedParameters来完成。 如果参数无效,那么服务器会返回“错误的请求”的请求参数添加到验证参数的集合。
Answer 6:
我建议以下元的资源和方法。
让参数主动和/或对其进行验证:
> PUT /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Content-Type: application/json
> Connection: close
>
> {'active': true, 'require-valid': true}
>
< HTTP/1.1 200 OK
< Connection: close
<
检查参数积极有效的:
> GET /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Connection: close
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Connection: close
<
< {
< 'active': true,
< 'require-valid': true,
< 'valid': {'status': false, 'reason': '...'}
< }
<
Answer 7:
在静止环境中,每个URL是一个独特的资源。 你有什么资源? 金融计算器真的没有任何明显的资源。 你需要深入到你所调用的参数并拉出资源。 例如,贷款分期偿还日程表可能是一个资源。 日历的URL可能包括起始日期,期限(以月或Y一代),期限(当利息复利),利率,和初始的原则。 所有这些值必须支付的特定日历:
http://example.com/amort_cal/2009-10-20/30yrsfixed/monthly/5.00/200000
现在,我不知道你是什么计算,但您的参数列表的概念不健全REST风格。 至于别人说,你的要求,上述声音更XMLRPC。 如果你正在尝试为REST您需要的名词。 计算不名词,它们是动词名词上采取行动。 你需要把它周围拉名词你的Calcs(计算)的。
Answer 8:
编辑:实际上,URI会阻止GET
从剩余幂请求。
为验证然而,使用的HTTP状态代码以通知请求的有效性(以创建一个新的或修改现有的“参数”)将适合雷斯特夫尔模型。
报告背部采用了400 Bad Request
状态代码,如果提交的数据是/是无效的,要求必须重新提交被(之前被改变HTTP / 1.1状态代码 )。
这依赖于在提交时确认,虽然,而不是推迟它在你的用例。 其他答案有那种情况下适当的解决办法。
文章来源: How to create REST URLs without verbs?