[ADP-375] Using 'expand' query parameter

Overview

In some cases, instead of providing the full content of the related resource, we only include an relatedResourceId field to inform the client of the related resource's ID. It is necessary to have a mechanism to expand this ID into a complete resource object.

Guidance

It is recommended to use expand to expand the related resourceId field into a complete resource object.
WARNING
Naming the relatedResource field can be challenging. Using resource-type does not inherently convey that it represents the resource-id by default. Conversely, using resource-id might make it difficult to expand into a full resource object. Here, we acknowledge that resource could also refer to an id. Alternatively, you MAY establish your own convention, such as:
- Convention 1:
  - resource: { resource-id : $ID } by default
  - resource: { FULL_CONTENT } by expand
- Convention 2:
  1. resourceId: $ID by default
  2. Remove above and provide resource: { FULL_CONTENT } by expand
Either way, it is essential to document this convention clearly.
It is optional to use expand to include an additional field in the response that is not part of the default response schema.
- In contrast to embed, expand is designed to encompass not only complete resources but also non-resource properties.

Example

Define the expand Parameter:
- The API should support an expand query parameter that accepts a comma-separated list of resource relationships to expand.
Example:
```
GET /orders/{orderId}?expand=customer,items
```

Return Expanded Resource Objects:

When the expand parameter is not used, the API would return the relative resourceId by default.

Example Response:

json

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

When the expand parameter is used, the API should return the full resource objects for the specified relationships in the response.

Example Response:

json

{
  "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
    }
  ]
}

Document the Usage:
- Clearly document the expand parameter in the API documentation, including examples of how to use it and the expected response format.

Reference

Design Reference

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

[ADP-375] Using 'expand' query parameter ​

Overview ​

Guidance ​

Example ​

Reference ​