REST API可以至少以两种方式拥有参数:

作为url路径的一部分(即/api/resource/parametervalue) 作为查询参数(例如/api/resource?=参数值)

这里的最佳实践是什么?什么时候使用1,什么时候使用2,有什么一般的指导方针吗?

真实世界的例子:Twitter使用查询参数来指定间隔。(http://api.twitter.com/1/statuses/home_timeline.json?since_id=12345&max_id=54321)

把这些参数放在URL路径中会被认为是更好的设计吗?


当前回答

以下是我的观点。

查询参数被用作请求的元数据。它们充当现有资源调用的过滤器或修饰符。

例子:

/ / 2014-08-08 /日历事件

应该给出当天的日历事件。

如果需要特定类别的事件

/日历/ 2014-08-08 /事件吗?类别=约会

或者你需要超过30分钟的比赛

/日历/ 2014-08-08 /事件吗?时间= 30

试金石测试是检查在没有查询参数的情况下是否仍然可以提供请求。

其他回答

根据REST实现,

1)路径变量用于对资源的直接操作,如联系人或歌曲 前女友. . 获取etc /api/resource/{songid}或 GET etc /api/resource/{contactid}将返回相应的数据。

2)查询perms/参数用于间接资源,如一首歌的元数据 . ., GET / api /资源/ {songid} ?Metadata =genre它将返回特定歌曲的类型数据。

如果有记录在案的最佳实践,我还没有找到它们。然而,当我决定在url中放置参数时,这里有一些指导原则:

可选参数往往更容易放在查询字符串中。

如果您希望在参数值与现有资源不对应时返回404错误,那么我倾向于使用路径段参数。例如:/customer/232,其中232不是有效的客户id。

然而,如果你想返回一个空列表,那么当参数没有找到时,我建议使用查询字符串参数。例如/联系人吗?name =戴夫

如果一个参数影响URI空间的整个子树,则使用路径段。例如,语言参数/en/document/foo.txt和/document/foo.txt?语言= en

我希望唯一标识符位于路径段中,而不是查询参数中。

uri的官方规则可以在这个RFC规范中找到。这里还有另一个非常有用的RFC规范,它定义了参数化uri的规则。

我通常倾向于#2,作为查询参数(即/api/resource?=参数值)。

第三种选择是将parameter=value放到函数体中。

这是因为它可以更好地用于多参数资源,并且具有更强的可扩展性以供将来使用。

不管你选哪一个,确保你只选一个,不要混搭。这导致了一个令人困惑的API。

我看到很多REST api不能很好地处理参数。经常出现的一个例子是URI包含个人身份信息。

http://software.danielwatrous.com/design-principles-for-rest-apis/

我认为一个必然的问题是,当一个参数根本不应该是一个参数,而应该被移动到请求的HEADER或BODY。

根据universe-resource-locator提供的“上下文”“打包”和POST数据,这对于定位器来说意味着#1。

注意第二条的局限性。比起第一条,我更喜欢post。

注:此处讨论的局限性

POST参数内容是否有最大大小?

GET请求的长度有限制吗?和最大大小的URL参数在_GET

附注:这些限制是基于客户端功能(浏览器)和服务器(配置)。