Using link expansion

When you request a collection resource, you might want the server to return not only that resource, but also one or more of its linked resources. Link expansion enables you to retrieve related resources in a single request to the server instead of having to issue multiple separate requests. You can use this technique to reduce the number of round-trip communication requests to the server, enhancing the performance of your application.

Expanding resources

To retrieve a collection and to expand its items, you can specify the expand query parameter with a value of true. This eliminates having to issue multiple follow-on requests (one for the collection and another for each of its items).

Using the expand query parameter:

curl -X GET '<baseURL>/v2/someCollection?expand=true'

The expanded items array in the JSON response:

{
  "href": "<baseURL>/v2/someCollection?expand=true",
  "offset": 0,
  "limit": 10,
  "items" : [
    {
      "href": "<baseURL>/v2/someCollection/37e60a14-9198-4b38-8bc3-f3924e2b6fe4?expand=true",
      "name" : "My sample name"
    },
    {
      "href": "<baseURL>/v2/someCollection/D1548691-47DF-41B6-A7B7-77516A76D62C",
      "name" : "My other sample name"
    }
  ]
}

In the JSON response, the items is no longer a link. Instead, it has been expanded in-line and included in the response body.

Expanding subresources

There might be occasions when you want to only expand one subresource or a list of subresources. To do this, specify the name of the subresource as the value of the expand query parameter.

If you want to expand more than one subresource, include the names of the subresources as a comma separated list.

Expanding a subresource:

curl -X GET '<baseURL>/v2/someCollection/37e60a14-9198-4b38-8bc3-f3924e2b6fe4?expand=someSubResource'

The expanded subresource in the JSON response:

{
    "href": "<baseURL>/v2/someCollection/37e60a14-9198-4b38-8bc3-f3924e2b6fe4?expand=someSubResource",
    "name" : "My sample name",
    "someSubResource": {
      "href": "<baseURL>/v2/someCollection/37e60a14-9198-4b38-8bc3-f3924e2b6fe4/someSubResource",
      "name" "My sample some sub resource name"
    },
    "someSubCollections": {
      "href": "<baseURL>/v2/someCollection/37e60a14-9198-4b38-8bc3-f3924e2b6fe4/someSubCollections"
    }
}

If you have suggestions for improving this article, let us know!