http - 这是 REST API 的有效映射吗？

Question

我在处理用户能够创建和管理不同类型资源的系统的 REST API 时提出了以下映射。

// READ OPERATIONS
GET /objects               => read collection meta
GET /objects/[id]          => read single element
GET /objects/?[query]      => read a number of elements
GET /objects/?all          => read all elements

// CREATE / UPDATE OPERATIONS
PUT /objects               => possibly create the collection and update its meta
PUT /objects/[id]          => possibly create and update a single element
PUT /objects/?all          => update the entire content of the collection
POST /objects              => create new objects or update existing objects
PATCH /objects             => partially update the collection meta
PATCH /objects/[id]        => partially update a single element
PATCH /objects/?all        => partially update all the elements
PATCH /objects/?[query]    => partially update a number of elements

// DELETE OPERATIONS
DELETE /objects            => delete the collection
DELETE /objects/[id]       => delete a single element
DELETE /objects/?all       => empty the collection
DELETE /objects/?[query]   => delete a number of elements

这里有一些关于系统的更多信息:

• 每个资源可以是一个简单的资源，也可以是一个类似集合的资源；
• 每个资源，无论是否是集合，都有自己需要访问和操作的属性；
• API 必须支持批量(而非批量)操作。

我还检查了以下替代方案:

1. 使用 /collection 访问集合的元素集，使用 /collection?meta 访问集合自己的数据；
2. 使用全新资源访问集合自身的数据，例如 /collections/path/to/collection。

我不喜欢备选方案 n。 1)因为对我来说，它在语义上感觉很差。相比之下，当我提到一个盒子时，我实际上指的是盒子本身，而不是它的内容。

我不喜欢备选方案 n。 2) 因为一个资源最终有自己的数据被另一个资源公开，复制 url 并使“我应该使用哪个 url”的问题不像我希望的那样微不足道。

因此，我的问题:

1. 我提出的映射是否是 REST API 的有效、适当的映射？它是否尊重 REST 原则？我不是在问它是否是最好的映射。我问的是它的有效性。
2. 如果不是，哪一种替代方案更好，为什么？

请原谅我的英语，我不是母语人士。

Answer 1

我认为 API 设计看起来不错，但后来我重新阅读了您开头的评论:

where users are able to create and manage resources of different types.

如果您的系统资源是不同类型的，为什么要使用仅适用于通用 object 的中立的、无类型的 API 来公开它们？

RESTful API 设计的第一部分是识别系统中的名词，这些名词应该强烈地被视为暴露为 URI 的候选者。我强烈建议您尝试获取比 object 更具体的内容，并使用更清晰的 URI 为系统的业务功能建模。

而且你的英语很好!