GitBook: [master] 69 pages modified

rest-api-guidelines/execution/choosing-fields-and-embedded-resoruces.md

@@ -0,0 +1,88 @@
+# 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.
+