Page History
...
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. Here is an example of a resource object with one embedded resource:
| 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"
}
}
}
]
}
} |
Here are a few notes regarding the above resource object and embedded resources in general:
- The name of the embedded resource in our example is contacts.
- Other embedded resource names can be included. Each embedded resource name is a sub-property of the _embedded property.
- Embedded resources can singular (i.e., the value is just a resource object) or plural (i.e., the value is an array of resource objects). If the embedded resource object is singular by definition, then just set the value to a resource object. Otherwise, use an array even if there is only one embedded resource object. Otherwise, adding an array later on could break clients.
- Each embedded resource object should also include its own self relation link (which is identified by the _links property).
