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路径中会被认为是更好的设计吗?


当前回答

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

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

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

其他回答

在我看来,参数应该更好地作为查询参数。url用于标识资源,而添加的查询参数用于指定您想要的资源的哪一部分、资源应该具有的任何状态等等。

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

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

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

这取决于设计。HTTP上的REST没有uri规则(主要是它们是唯一的)。通常这涉及到品味和直觉的问题……

我采取以下方法:

url path-element:资源和它的path-element组成了一个目录遍历和一个子资源(例如/items/{id}, /users/items)。不确定的时候问问你的同事,如果他们认为遍历和他们认为在“另一个目录”最有可能的路径元素是正确的选择 Url参数:当没有遍历时(有多个查询参数的搜索资源就是一个很好的例子)

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

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

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

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

以下是我的观点。

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

例子:

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

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

如果需要特定类别的事件

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

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

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

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