Page History
...
HAL intentionally defined link relations to be simple. To support the self-documenting and self-discovery discoverability intent of a RESTful API, clients should be able to use the OPTIONS HTTP method to get a list of all supported HTTP methods for a given API. The list of all support HTTP methods is expected to appear in the Allow response header. The SRP HTTP Framework handles this automatically.
_embedded
This property contains one or more sub-properties. Each sub-property name defines an embedded resource object within the current resource object. These embedded resource objects (which are technically sub-resources) represent a partial or whole resource object that should have its own API (i.e., URI endpoint). The reason for including embedded resource objects will vary and are always based on the developer's needs. Typically embedded resource objects are added to provide one API with enough additional resource information to prevent the need for additional API calls. This is very common with collection APIs. For example, in the above resource object we identified a URI with a relation of collection. An inspection of the URI itself reveals that the endpoint is simply /customers. The absence of a unique identifier to a customer (i.e., /customers/1) is expected to mean "all customers", also referred to as "the collection of customers".
At a minimum, the GET /customers API should return all URIs related to each customer in the collection. However, perhaps a client wants to use this API as a way to provide visitors with a list of customers. If the client intends to display other customer properties (e.g., first and last name), then the client would need to make a GET /customers/{id} request for each URI. This could become a resource intensive process. It would be far better if the initial GET /customers request not only returned all the URIs, but also a partial resource object that can be immediately consumed and used by the client.
| Code Block | ||
|---|---|---|
| ||
{ "_embedded":{ "contacts":[ { "firstName":"Harrison", "lastName":"Haufler", "_links":{ "self":{ "href":"https://www.examples.org/api/customers/266" } } }, { "firstName":"Haydee", "lastName":"Denooyer", "_links":{ "self":{ "href":"https://www.examples.org/api/customers/271" } } }, { "firstName":"Heike", "lastName":"Berganza", "_links":{ "self":{ "href":"https://www.examples.org/api/customers/254" } } }, { "firstName":"Helga", "lastName":"Fredicks", "_links":{ "self":{ "href":"https://www.examples.org/api/customers/202" } } }, { "firstName":"Herman", "lastName":"Demesa", "_links":{ "self":{ "href":"https://www.examples.org/api/customers/125" } } }, { "firstName":"Herminia", "lastName":"Nicolozakes", "_links":{ "self":{ "href":"https://www.examples.org/api/customers/287" } } }, { "firstName":"Hillary", "lastName":"Skulski", "_links":{ "self":{ "href":"https://www.examples.org/api/customers/186" } } }, { "firstName":"Howard", "lastName":"Paulas", "_links":{ "self":{ "href":"https://www.examples.org/api/customers/132" } } } ] } } |
