这是RESTful吗?

时间:2013-09-11 21:31:04

标签: api rest url routing

我对收集URI应该返回的内容感到有些困惑。

假设我有一个很大的元素/users集合。然后我们有了预期的:

GET /users/123           // returns user element with identifier 123

但应该

GET /users

返回?如果集合很大,并且元素很大,那么返回所有元素可能不是一件好事。也许相反,GET级别的/users请求应返回元素摘要(标识符和可能的一些属性),而GET请求/users/ } level应返回实际元素。然后你可以做类似的事情;

GET /users
   > [{name: abc, id: 1}, {name: def, id: 2}, {name: ghi, id: 3}, ...]
GET /users/2
   > {name: def, prop1: *, prop2: *, ...}

如果要在完整请求之前预览重要的应用程序域属性,这可能是懒惰加载数据的好方法。有了这个,为了应用查询,你会做类似

的事情
GET /users?prop1=value           // returns element summaries of elements with prop1=value
GET /users/?prop1=value          // returns elements with prop1 = value

这种方法可以吗?或者其他方法作用于/users然后松散意义..(例如PUT /users?)

1 个答案:

答案 0 :(得分:2)

我个人喜欢/ users不返回所有用户的样式,但会返回查询特定用户所需的信息。所以摘要方法是我通常会写它的方式。

如果您正在过滤或查询,我会选择您提供的第一个:

GET /users?prop1=value

我不关心第二个

GET /users/?prop1=value

因为它很容易被误解或导致令人困惑和意外的错误(缺少一个斜线仍然有效但完全改变了结果)。

您可能希望采用替代网址的方法,根据搜索参数(例如

)返回特定用户
GET /users?prop1=value    // returns element summaries based on results of prop1 matching
GET /users/find?prop1=value // returns elements with prop1 = value

显然你的措辞可能会改变(查找/搜索),或者你可以使用完全不同的URI,但我尽量避免两个不同含义是单个字符/符号的东西,以避免意外的错误。另一种选择是确保在提供的文档中清楚地概述这一点,以便任何使用API​​的人都会收到有关此潜力的警报。

实际上扩展这个我将使用all构造。

所以我没有使用find / search,而是提供:

GET /users                   // returns summaries
GET /users/#                 // returns element
GET /users/all               // returns all elements
GET /users/all?prop1=value   // returns all elements that match the filter