Article

Handling Requests and Responses

Write a request and handle a response from the Apple Music API.

Overview

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, https://api.music.apple.com/v1/.

Follow this part of the path with either the catalog/ or 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.

GET https://api.music.apple.com/v1/catalog/{storefront}/genres/{id}

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:

GET https://api.music.apple.com/v1/me/ratings/albums/{id}

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.)

For example:

  • If the request is for an existing single resource object, the status code is 200 (OK) and the data array 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 data array.

  • If the request is for multiple resource objects by ID, the status code is 200 (OK) and the data array 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 data array 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 errors array 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 errors array contains error objects for the errors that occurred.

See Also

Essentials

Getting Keys and Creating Tokens

Obtain developer tokens and keys needed to make requests to the Apple Music API.

Handling Relationships and Pagination

Fetch related objects as part of your original request and paginate the results from the Apple Music API.

Storefronts and Localization

Pick a country-specific geographic region from which to retrieve catalog information, or retrieve information from the user's personal library.

Common Objects

Understand the base types used to construct the JSON data you receive.