[ADP-375] 使用 'expand' 展開資源

概述

在某些情況下，我們不提供相關資源的完整內容，而是只包括一個 relatedResourceId 屬性，以通知客戶端相關資源的ID。因此，需要有一個機制來將這個ID展開為完整的資源對象。

指導原則

• 建議使用 expand 來展開相關的 resource 欄位到完整的資源對象。

  WARNING

  命名相關資源屬性可能會很具挑戰性。使用 resource-type 並不一定會暗示它代表了 resource-id，反之，使用 resource-id 可能會使得展開到完整的資源對象變得困難。這裡，我們承認 resource 也可能指的是一個id。或者，你可以制定自己的約定，例如：

  • 約定 1：
    • resource: { resource-id : $ID } 默認
    • resource: { FULL_CONTENT } 通過 expand
  • 約定 2：
    1. resourceId: $ID 默認
    2. 移除上述內容，並通過 expand 提供 resource:

  無論哪種方式，清楚地記錄這個約定都是至關重要的。

• 可以(MAY)選擇使用 expand 來在回應中包括一個額外的欄位，該欄位不屬於默認回應內容。
  • 與 embed 相比，expand 設計用於涵蓋不僅僅是完整的資源，還包括非資源屬性。

範例

1. 定義 expand 參數：

   • API 應該支持一個 expand 查詢參數，該參數接受一個逗號分隔的列表，用於指定要展開的資源關係。

   示例：

   GET /orders/{orderId}?expand=customer,items

2. 返回展開的資源對象：

   • 當不使用 expand 參數時，API 將返回默認的相對 resourceId。

   示例回應：

   {
     "orderId": "12345",
     "customer": "67890"
   }

   • 當使用 expand 參數時，API 應該返回指定關係的完整資源對象。

   示例回應：

   {
     "orderId": "12345",
     "customer": {
       "customerId": "67890",
       "name": "John Doe",
       "email": "john.doe@example.com"
     },
     "items": [
       {
         "orderItemId": "1",
         "productId": "987",
         "productName": "Widget",
         "quantity": 2,
         "price": 25.00
       },
       {
         "orderItemId": "2",
         "productId": "654",
         "productName": "Gadget",
         "quantity": 1,
         "price": 50.00
       }
     ]
   }

3. 記錄使用方法：

   • 清楚地記錄 expand 參數在 API 文件中的使用方法，包括如何使用它和預期的回應格式。

參考

設計參考

• https://docs.digitalriver.com/commerce-api/resources/common-shoppers-and-admin-apis-reference/fields-and-expand-query-parameters