休息标准:路径参数或请求参数

Question

我正在创建一个新的REST服务.

将参数传递给REST服务的标准是什么.从Java中的不同REST实现,您可以将参数配置为路径的一部分或作为请求参数.例如,

路径参数 http://www.rest.services.com/item/b

请求参数 http://www.rest.services.com/get?item=b

有谁知道传递参数的每种方法的优点/缺点.似乎将参数作为路径的一部分传递似乎与REST协议的概念更吻合.也就是说,单个位置表示唯一的响应,对吗？

Answer 1

作为一般规则,路径往往是缓存的,参数往往不是.

所以...

GET /customers/bob

VS

GET /customers?name=bob

第一个更可能被缓存(假设正确的标题等),而后者可能不会被缓存.

Answer 2

tl;博士:你可能想要两者.

项目#42存在:

GET /items/42
Accept: application/vnd.foo.item+json
--> 200 OK
{
    "id": 42,
    "bar": "baz"
}

GET /items?id=42
Accept: application/vnd.foo.item-list+json
--> 200 OK
[
    {
        "id": 42,
        "bar": "baz"
    }
]

项目#99不存在:

GET /items/99
Accept: application/vnd.foo.item+json
--> 404 Not Found

GET /items?id=99
Accept: application/vnd.foo.item-list+json
--> 200 OK
[
]

解释和评论

1. /items/{id}返回一段item时间/items?id={id}返回item-list.
2. 即使过滤中只有一个元素,item-list仍会返回单个元素的列表以保持一致性(与元素本身相反).
3. 恰巧这id是一个独特的财产.如果我们要过滤其他属性,这仍然可以完全相同的方式工作.
4. 集合资源的元素只能使用唯一属性(例如,键作为集合的子资源)命名,原因很明显(它们是普通资源,URI是唯一标识资源的).
5. 如果在使用过滤器时未找到该元素,则响应仍然OK仍然包含一个列表(尽管是空的).仅仅因为我们要求包含不存在的项目的过滤列表并不意味着列表本身不存在.

因为它们是如此不同且独立有用,您可能想要两者.客户端希望区分所有情况(例如,列表是否为空或列表本身不存在,在这种情况下,您应该返回404 /items?...).

免责声明: 这种方法绝不是"标准".尽管我觉得分享,但这对我来说非常有意义.

PS:命名项集合"get"是代码气味; 喜欢"物品"或类似物.

Answer 3

您的第二个"请求参数"示例不正确,因为"get"包含在路径中.GET是请求类型,它不应该是路径的一部分.

有4种主要类型的请求:

 GET
 PUT
 POST
 DELETE

GET请求应始终能够在请求正文中没有任何信息的情况下完成.此外,GET请求应该是"安全的",这意味着请求不会修改重要数据.

除了上面提到的缓存问题之外,URL路径中的参数往往是必需的和/或预期的,因为它们也是路由的一部分,而在查询字符串中传递的参数更加可变,并且不会影响应用程序的哪个部分请求被路由到.虽然也可能通过url传递一组可变长度的参数:

GET somedomain.com/states/Virginia,California,Mississippi/

作为这个主题的入门读物的好书是"Restful Web Services".虽然我会警告你准备好略过一些冗余的信息.