> For the complete documentation index, see [llms.txt](https://adidas.gitbook.io/api-guidelines/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adidas.gitbook.io/api-guidelines/rest-api-guidelines/execution/choosing-fields-and-embedded-resoruces.md).

# Choosing Fields and Embedded Resources

## Response Message Fields

Every request that may result in a response with a non-trivial body **SHOULD** implement the `fields` query parameter. If provided, the value of this parameter must be a comma-separated list of top-level response message fields.

Upon receiving such a request, in the event of a 2xx response, the service **SHOULD** respond with a message that includes only top-level fields specified in the `fields` parameter. That includes HAL-specific fields (`_links` and `_embedded`).

### Example

Retrieve only some details of an Order resource:

HTTP Request

```
GET /order/1234?fields=_links,orderNumber,status HTTP/1.1
Accept: application/hal+json
```

HTTP Response

```
HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "_links": {
    "self": { "href": "/orders/1234" },
    "author": { "href": "/users/john" },
    "items": [ ... ]
  },
  "orderNumber": 1234,
  "status": "pending"
}
```

## Embedded Resources

Similarly to the `fields` query parameter, every request that might result in a response containing related embedded resource representations **SHOULD** implement the `embedded` query parameter. If, provided the value of the `embedded` query parameter **MUST** be a comma-separated list of relation identifiers.

Upon receiving such a request, in the event of a 2xx response, the service **SHOULD** respond with a message that "embeds" (see HAL `_embedded` field) only the related resources specified in the `embedded` parameter.

### Example

Embed only information about the Author of an Order resource. We are not interested in Items that are in this order.

HTTP Request

```
GET /order/1234?embed=author HTTP/1.1
Accept: application/hal+json
```

HTTP Response

```
HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "_links": {
    "self": { "href": "/orders/1234" },
    "author": { "href": "/users/john" },
    "items": [ ... ]
  },
  "orderNumber": 1234,
  "itemCount": 42,
  "status": "pending",
  "_embedded": {
    "author": {
      "_links": { "self": "/users/john" },
      "name": "John Appleseed",
      "email": "john@apple.com"
    }
  }
}
```

## Reasonable Defaults

When `fields` and `embedded` parameters are not provided or not implemented the server **SHOULD** return reasonable default field and/or embedded resources. The defaults **MUST** always contain the `_links` field, where available.

## Resource Variants

The facility of `fields` and `embedded` parameters doesn't impose any restriction of creating new resource variants.

It is OK to create a new resource just as a compound resource only to provide selected fields or blend-embed some existing resources together.