Write a request and handle a response from the Apple Music API.
After adding the developer token and music user token to the header, you're ready to compose your request to get data from the API.
Compose a Request
Apple Music API requests have common components. To compose a request, first specify the root path,
Follow this part of the path with either the
library/ path parameter. The
catalog path accesses the entire Apple Music library. The
library path accesses the contents of the user's personal music library.
Follow this path with any parameters that are specific to the endpoint. For example, to request information about a specific genre, construct a URL that includes the ID of the genre in the path.
When requesting resources from the Apple Music catalog, you must include the storefront in the path. When requesting resources from the user's personal library, you replace the storefront information with the
me string, as shown in the following example:
Every resource has a unique identifier in the Apple Music catalog. Resources in the user's personal library also have unique identifiers that are different from the Apple Music catalog identifier. If you (or the user) remove an item from the user's library, iTunes deletes the associated library identifier. If you or the user add that resource back later, iTunes generates a new identifier for the resource.
Most requests return only the requested resource. For information about how to request related resources at the same time, see Handling Relationships and Pagination.
Handle a Response
The core document object that appears in a response is the ResponseRoot object. This object contains different arrays and groups of Resource objects, which contain the information requested about the artist, album, song, and so on.
If a request is successful, the HTTP status code in the response is in the 200 range. The body of the response contains either the requested array of resource objects in the
data array or the result of the request as a map called
results, where resource types are the members and the corresponding values are groups of resource objects. For example, if you fetch resources by type, the resource objects are contained in the
data array of the ResponseRoot object. (For the common resource members, see Resource object and Relationship object.) If you successfully modify or delete resources, the status code is 204 and the body is empty.
If the status code indicates an error, the response may contain information in the
errors array about one or more errors that occurred. The status code indicates the primary error, but you should examine the contents of the
errors member of the Root object for details about individual errors. (See Error and HTTP Status Codes.)
If the request is for an existing single resource object, the status code is 200 (OK) and the
dataarray contains the requested resource object.
If the request is for a single resource object that doesn’t exist, the status code is 404 (Not Found) and the response doesn’t contain a
If the request is for multiple resource objects by ID, the status code is 200 (OK) and the
dataarray includes the existing resource objects.
If the request is for multiple resource objects by ID and none of the resources exist, the status code is 200 (OK) and the
dataarray is empty.
If you make a successful request to an endpoint that returns results, the status code is 200 (OK) and the response includes the results object.
If the request isn’t supported as specified, the status code is 400 (Bad Request) and the
errorsarray contains an error object for any identified problem.
If errors are encountered when the request is processed, the status code is in the 500 range and the
errorsarray contains error objects for the errors that occurred.