REST URI设计

时间:2016-07-12 09:08:51

标签: rest entity-model

在开发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}等路径上的资源。

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

1 个答案:

答案 0 :(得分:1)

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

资源是像Objects这样的通用概念。 资源具有两个可识别的基本属性,并且可以从外部访问一个或多个表示。

在您的第一个示例/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 市场客户合同计划的子资源>

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

即使客户不应该尝试解释您的uri,您的申请也应该会为这些资源返回有用的结果。

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

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

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