REST URI 设计

Question

在开发 RESTFul Web 服务时，我对请求实体的建模感到困惑。处理请求所需的所有数据是否应该是实体的一部分，或者我应该将一些数据移动到 URL 路径中（假设我在这些数据中有逻辑层次结构）。

例如：

路径

/api/payment/3pResponse

实体架构

{
  "marketplacedId" : String,
  "customerId: String,
  "contractId: String,
  "planId": String,
  "3pResonse" : {},
  "3pResponseURI" : "string" 
}

对

路径

/api/payment/marketplaces/{mktId}/customers/{customerId}/contracts/{contractId}/plans/{plandId}/3pResponse

实体架构

{
  "3pResonse" : {},
  "3pResponseURI" : "string" 
}

请注意，路径上的资源（例如 /api/payment/marketplaces/{mktId}）可能并不真正存在于我的应用程序中。

两者中的任何一个在技术上都可行，但我想了解在这种情况下围绕实体建模的最佳实践。

Answer 1

当您设计 REST API 时，您将功能需求映射到您的资源，类似于面向对象的设计方法。

资源是一个像对象一样的通用概念。 一个资源有两个基本属性，它是可识别的，并且有一个或多个可从外部访问的表示。

在您的第一个示例 /api/payment/3pResponse 中，您只有一个 3PResponse 资源，您可以使用 PUT 方法对其进行完全更新。

当您尝试访问它们时，您可以通过矩阵参数识别资源。 （这只是一种方法，还有其他方法）

/api/payment/3pResponse;marketPlace=x;customerId=y;contractId=z;planId=k

在你的第二种方法中

/api/payment/marketplaces/{mktId}/customers/{customerId}/contracts/{contractId}/plans/{plandId}/3pResponse

3pResponse 是 marketplaces、customers、contracts 和 plans 的子资源>.

使用这种方法，人们可能会想到还有一个资源 /api/payment/marketplaces/ 返回一个市场列表 或者有一个资源/api/payment/marketplaces/{mktId}/customers/{customerId}/contracts/{contractId} 为客户返回合同。

即使客户端不应尝试解释您的 uri，您的应用程序也应该为这些资源返回有用的结果。

Stefan Tilkov 有一篇关于 REST API 设计的精彩演讲 REST: I don't Think it Means What You Think it Does

比 URI 和资源的实际设计更重要的是保持 URI 稳定。

引自Tim Berners-Lee：“酷 URI 不会改变”。