Fetch relationships and paginate response results from the Apple Music API.
You can fetch the resources and related objects your app needs in a single request. To get related objects, you fetch specific relationships along with the resource objects. If the query results contain too many objects, you can use pagination to fetch the next set of objects.
Fetch Resource Relationships
To reduce response sizes and improve performance, not all available relationships of a resource object—such as an album, song, playlist, or music video—are included by default. You can include additional related resources in the response by using the
include query parameter.
There are three possible default behaviors for fetching resources in relationships:
The resources are included, with their attributes, as secondary resource objects.
The resources are included, without their attributes, as resource identifiers only.
The relationship is omitted from the response entirely and must be explicitly included.
For example, these Album relationships have different default behaviors:
tracksrelationship includes the resource objects for the album’s songs and music videos, which are typically essential for working with albums.
artistsrelationship only includes resource identifiers for the artist or artists associated with the album and excludes the
attributesmember in each resource object. This relationship allows you to easily link to an artist from an album, although some artist attributes are also attributes of the album.
genresrelationship is omitted by default. This relationship is seldom used, and the names of the genres already appear as an attribute of the album,
See the corresponding object model reference for the default behavior of other objects.
include parameter to include the resource objects for one or more available relationships in the response. The value of the
include parameter is a comma-separated list of the relationship names. Relationships that include resource objects by default don’t have to be specified in the list; they’ll continue to be included along with the specified relationships. For example, when fetching an Artist object, you can request that the
playlists objects be included:
To fetch a relationship exclusively, specify the name of the relationship after the
id path parameter. For example, fetch just the tracks belonging to an album:
Not all objects in a relationship are fetched by default. See the corresponding object model reference for the default fetch limits. To specify the number of objects fetched, use the
limit resource parameter. For example, you can fetch an artist's first five albums:
Fetch Resources by Page
GET requests support pagination of the objects or an object’s relationships. If you specify a
limit parameter, the number of resources returned is restricted to that limit. If no limit is supplied, the default limit is used. If you reach the limit to the number of resource objects in a response, the response contains a subset of the resource objects matching your criteria, and more requests are needed to get the rest of the objects.
See the corresponding resource’s object model for the default fetch limit. If there are more resource objects than permitted by the fetch limit, the ResponseRoot object contains a
next member whose value is a subpath you use in the next request. The subpath contains the
offset parameter that specifies the next page. Similarly, a Relationship object may contain a
next member that you use to fetch more objects in a relationship.
For example, fetch all objects of a resource type, but specify the amount in the response by using the
If there are more objects to fetch, the response contains a
next subpath, and optionally, the
limit parameter again, in the next request:
Continue requesting the resource objects until the
next member no longer appears in the response.