mirror of
https://github.com/adidas/api-guidelines.git
synced 2025-10-25 15:19:19 +00:00
89 lines
2.7 KiB
Markdown
89 lines
2.7 KiB
Markdown
# 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
|
|
|
|
```text
|
|
GET /order/1234?fields=_links,orderNumber,status HTTP/1.1
|
|
Accept: application/hal+json
|
|
```
|
|
|
|
HTTP Response
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
GET /order/1234?embed=author HTTP/1.1
|
|
Accept: application/hal+json
|
|
```
|
|
|
|
HTTP Response
|
|
|
|
```text
|
|
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.
|
|
|