REST 资源路径设计

Question

我正在开发 REST 服务，并且我正在努力遵守 Roy Fielding 医生的约定和指导方针。

我将我的服务描述为暴露一组资源的端点。资源由 URI 标识，API 客户端可以通过使用 HTTP 语义(即，不同的 HTTP 动词映射到 URI 上的相应操作)来操作资源。

指南指出，这些 URI 应以分层方式定义，反射(reflect)对象层次结构。这在资源创建中非常有用，因为在后端我们需要数据来执行创建操作。但是，在进一步的操作中，URI 中包含的很多信息甚至不会被服务使用，因为通常仅资源 Id 就足以唯一标识操作目标。

一个例子:考虑一个公开产品创建和管理的 Api。还要考虑产品与品牌相关联。在创建时，执行以下操作是有意义的:
HTTP POST/Brand/{brand_id}/Product
[包含创建产品所需的输入的正文]

该创建返回一个 HTTP 201，该 HTTP 201 带有一个位置 header ，该 header 公开了新创建的产品的位置。

在进一步操作时，客户可以通过以下方式访问产品:
HTTP PUT/Brand/{brand_id}/Product/{product_id}
HTTP 删除/Brand/{brand_id}/Product/{product_id}
等等

但是，由于产品 ID 在产品范围内是通用的，因此可以像这样执行以下操作:
/产品/{product_id}
出于一致性原因，我只保留/Brand/{brand_id} 前缀。实际上，服务忽略了品牌 ID。你认为这是一个很好的做法，并且为了维护一个清晰、明确的 ServiceInterface 定义是合理的吗？这样做有什么好处，这是要走的路吗？

此外，任何有关 URI 定义最佳实践的指针都将不胜感激。

提前致谢

Answer 1

你是说:

Guidelines state that these URIs should be defined in an hierarchical way, reflecting object hierarchy.

虽然它经常以这种方式完成，但它与 RESTful API 设计并不真正相关。 Roy Fielding 有一个 nice article解决关于 REST 的常见误解。他甚至在那里说:

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server).

和

A REST API should be entered with no prior knowledge beyond the initial URI …

所以不要在你的 URL 中编码应该在资源内部传递的信息。即使您将所有 URL 替换为人工和无意义的 URI，RESTful API 也应该可以工作。 (我喜欢任何人都可以理解的 URI，但作为一种检查“RESTfullness”的心理练习，它非常好。)

为对象“层次结构”建模 URI 的问题在于层次结构并不像看起来那么明显。 (教师、类(class)和学生之间的对象层次是什么？)。对象通常位于一个关系网中，并不明显属于另一个对象之下。一个产品可能属于一个品牌，但您可能有多个供应商(涵盖多个品牌的产品子集)。 REST 非常适合表达复杂的关系网络。整个互联网/网络都是这样工作的。

无需在层次结构中对关系进行编码，只需在资源中定义一个指向相关对象的超链接即可。

对于您的具体示例，我将使用 POST/product/创建一个新产品，并在创建产品时在资源表示中提供指向您的/brand/xzy 的链接。

如果您想知道为特定品牌定义了哪些产品，只需在 GET/brand/xzy 的返回表示中包含链接列表。如果你想有一个明确的资源来表示这种关系，你仍然可以将 GET/brand/{id}/products 定义为 URL(或/brandproducts/xzy 或/34143453453)，并将其作为链接返回到你的品牌资源中。

不要过多考虑 URI 的设计，多考虑您在资源中提供的信息。确保它提供指向您的客户端在从您的 API 接收后可能想要查看或操作的所有资源表示的链接。