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方法完全更新該資源。

當您嘗試訪問它們時，可以通過matrix參數標識資源。 （這只是您可以做到的一種方式，還有其他方式）

/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，您的應用程序也有望為這些資源返回有用的結果。

Stefan Tilkov很好地介紹了REST API設計REST：我認為這並不意味着您認為它能做什么

與URI和資源的實際設計相比，最重要的是保持URI穩定。

Tim Berners-Lee的話 ：“酷URI不會改變”。