REST 资源路径设计 [英] REST resource path design

问题描述

我正在开发 REST 服务，我正在努力遵守 Roy Fielding 医生的约定和准则.

I'm developing a REST service, and I'm trying to adhere to Doctor Roy Fielding's conventions and guidelines.

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

I picture my service as an endpoint that exposes a set of resources. A resource is identified by an URI, and api clients can manipulate resources by using using HTTP semantics (i.e., different HTTP verbs map to the corresponding operations over URIs).

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

Guidelines state that these URIs should be defined in an hierarchical way, reflecting object hierarchy. This renders useful in resource creating, because on the backend we need the data to perform the create operation. However, on further manipulations, a lot of the information included in the URI is not even going to be used by the service, because generally the resource Id alone is enough to uniquely identify the operation target.

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

An example: Consider an Api that exposes the creation and management of products. Consider also that a product is associated with a brand. On creation it makes sense that the following action is performed: HTTP POST /Brand/{brand_id}/Product [Body containing the input necessary to the creation of the product]

创建返回一个带有位置标头的 HTTP 201，用于公开新创建的产品的位置.

The creation returns an HTTP 201 created with a location header that exposes the newly created product's location.

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

On further manipulations, clients could access the product by doing: HTTP PUT /Brand/{brand_id}/Product/{product_id} HTTP DELETE /Brand/{brand_id}/Product/{product_id} etc

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

However, since the product Id is universal in the product scope, the following manipulations could be performed like this: /Product/{product_id} I am only keeping the /Brand/{brand_id} prefix for coherence reasons. In fact, the brand id is being ignored by the service. Do you thing that this is a good practice, and is reasonable for the sake of maintaining a clear, unambiguous ServiceInterface definition? What are the benefits of doing this, and is this the way to go at all?

也将不胜感激任何有关 URI 定义最佳实践的指针.

Also any pointers on URI definition best practices would be appreciated.

提前致谢

推荐答案

你是说:

指南指出，这些 URI 应以分层方式定义，以反映对象层次结构.

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

虽然经常采用这种方式，但它与 RESTful API 设计并没有真正的相关性. Roy Fielding 有一个 好文章 解决了对 REST 的常见误解.他甚至说:

While it is often done this way it is not really relevant for a RESTful API design. Roy Fielding has a nice article addressing common misconceptions about REST. There he even says:

REST API 不得定义固定的资源名称或层次结构(客户端和服务器的明显耦合).

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

和

一个 REST API 应该在初始 URI 之外没有任何先验知识的情况下输入......

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

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

So don't encode information in your URL that should be passed inside the resource. A RESTful API should work even if you replace all your URLs with artificial and non-sensical URIs. (I like understandable URIs as anybody but as an mental exercise to check your "RESTfullness" it's quite good.)

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

The problem to model an URI for an object "hierarchy" is that the hierarchy isn't very often as obvious as it seems. (What is the object hierarchy between teacher, course, and student?). Often objects are in a web of relations and belong not clearly beneath another object. A product might belong to a brand but you might have multiple supplier (covering a subset of products for multiple brands). And REST is wonderful to express complex nets of relations. The whole internet/web works this way.

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

Instead of encoding the relationship in the hierarchy just define a hyperlink in your resource pointing to the related objects.

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

For your specific example I would use POST /product/ to create a new product and have a link to your /brand/xzy in the resource representation when creating the product.

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

If you want to know which products are defined for a specific brand, just include a list of links in the returned representation for GET /brand/xzy. If you want to have an explicit resource representing for this relationship you still could define GET /brand/{id}/products as an URL (or /brandproducts/xzy or /34143453453) and return it as a link in your brand resource.

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

Don't think so much about the design of your URIs, think more about the information you provide in your resources. Make sure it provides links to all the resource representations your client might want to view or manipulate after receiving it from your API.

这篇关于REST 资源路径设计的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！