api - 这是 RESTful 吗？

Question

我对集合 URI 应该返回什么有点困惑。

假设我有一个收藏，/users相当大的元素。然后我们就得到了预期的结果:

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

但是应该做什么

GET /users

返回？如果集合很大，并且元素也很大，那么返回所有元素可能不是一件好事。也许相反，GET请求 /users level 应返回元素摘要(标识符和可能的一些属性)，而 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？)

Answer 1

我个人喜欢/users 不返回所有用户而是返回查询特定用户所需的信息的风格。因此，我通常会采用摘要方法来编写它。

如果您要过滤或查询，我会选择您提供的第一个:

GET /users?prop1=value

我不关心第二个

GET /users/?prop1=value

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

您可能希望采用替代 URL 的方法来根据搜索参数返回特定用户，例如

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 构造。

因此，我不会使用查找/搜索，而是提供:

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