Meet Apple Music API and MusicKit

Justin Rennell: Hello and welcome to WWDC. My name is Justin, and I'm an engineer on the Apple Music development team. Today I’m going to give an introduction to MusicKit with a focus on the fundamentals of using Apple Music API. In this session, I’ll provide an overview of MusicKit client frameworks and how they integrate with the Apple Music API web service. I'll explain how to get access as a developer and specific details about using Apple Music API, including: Requesting content and resources, using limits and pagination to work with large resource collections, and how to find content in the catalog with the search endpoint. Finally, I'll provide a look at some personalized features available for Apple Music subscribers and how to provide access to them in your apps.

I'll start with a brief introduction to MusicKit and Apple Music API. MusicKit was first announced at WWDC in 2017. Since then, we have made improvements that make integrating with Apple Music easier and continue to add support for additional functionality. MusicKit is a combination of client frameworks and the Apple Music API. Used together, they make it possible to add Apple Music functionality to your apps. You can discover and fetch content from Apple Music, including artists, albums, playlists, and more, with functionality to search the catalog and browse popularity charts. With the user’s consent, MusicKit and Apple Music API let you authenticate subscribers to play available content and provide access to personalized features, including their music library, recommendations, and recently played history. MusicKit client frameworks provide the APIs needed to authenticate subscribers and start and control playback on a device. Client frameworks are available for apps on Apple platforms, web applications using JavaScript, and Android applications using the available SDK.

MusicKit on Apple platforms has everything you need to integrate Apple Music into your apps. Subscribers can authenticate or sign up within your app to start and control playback and access other personalized features. Available APIs accelerate calls to discover and access content from Apple Music with native support for resources and pagination. Many of the topics covered later about accessing and making requests to Apple Music API directly are handled by MusicKit on Apple platforms automatically. Developers writing apps for Apple platforms are encouraged to watch the session "Meet MusicKit for Swift" for an introduction to those APIs and the session "Explore more content with MusicKit" for more functionality.

MusicKit on the Web makes it easy to bring Apple Music to your applications using JavaScript. You can discover Apple Music content, let subscribers sign in to access personalized features and play content directly on your website. Full access to Apple Music API gives you the power to create unique music experiences. MusicKit provides a collection of built-in web components, including a full-featured media player. These components make it easy to get started and have the flexibility to customize for your experience.

MusicKit for Android lets you integrate Apple Music into your Android applications. Support for authenticating Apple Music subscribers, controlling content playback, and full access to Apple Music API allows you to build a rich music experience.

Apple Music API is the common JSON web service that provides access to discovery features and Apple Music catalog content. Authenticated subscribers can access personalized features, including their Music Library, Recommendations, and Recently Played history.

Next, I'll explain how to get access. To make requests to Apple Music API, you will need a Developer Token. For applications on Apple platforms, you can take advantage of automatic token management by enabling the MusicKit service for your app. This service can be found in the App ID section of the Apple Developer portal shown here.

For applications on other platforms, you can obtain a Developer Token by enrolling as a MusicKit developer on the Apple Developer portal. From there, you can request and download a private key. You will need to generate a JSON Web Token and sign it with your downloaded private key. A JSON Web Token is split in two parts. The first part is required headers, including the signing algorithm "alg," which must be ES256, and the key identifier "kid," which is included as part of your private key download. The second part of the token is claims. Apple Music API has three required claims: issuer ID “iss,” which is your team ID that can be found in the memberships section of the Apple Developer portal, issued at time "iat," which is represented by the number of seconds since the Epoch, and an expiration time "exp." This is in the same time format as the issued time. Tokens can be generated to expire a maximum of six months from when they were issued. For web applications, we encourage providing an origin claim, which will issue a token valid for your website only.

A valid, signed token must be supplied in the authorization header for all requests to Apple Music API. With the MusicKit service enabled for your applications on Apple platforms, this will be done automatically. MusicKit on the web must be configured with a token you generate to make requests to Apple Music API. More information about generating JSON Web Tokens can be found in the Apple Music API documentation. Now I will show you how to request resources using Apple Music API. Resources model Apple Music content, such as artists, albums, songs, playlists and more. Each has its own corresponding type. Resources can be fetched from Apple Music API endpoints through discovery features like search or by using their identifiers. Here is an example request URL to fetch a playlist resource from the API using its identifier. Apple Music API is hosted at api.music.apple.com. The path of the URL uses a RESTful pattern and represents the location for a resource or feature. The first element in the location is the version of the API, which is currently version 1. New versions may become available when significant changes are introduced. Versions maintain backwards compatibility with existing calls, even as enhancements to resources and new features are made available. For requests within the Apple Music catalog, the next section in the location represents the specific catalog to fetch from. Apple Music is a worldwide streaming service, and content can differ between regions, which we refer to as storefronts.

For information about storefronts and content availability, watch the session titled "Cross reference content with the Apple Music API." In this example, I will fetch a playlist from the catalog in the United States storefront, denoted by the two-letter country code “us.” The final part of this location is the resource’s identity, represented by its type "playlists" followed by its identifier.

Since Apple Music is available in many regions, support for localization is possible using the optional language tag query parameter "L." Here, I am specifying the language tag "en-US" for English. To fetch content localized in Spanish, I could specify the tag “es-MX.” To keep things simple, I will not specify a language tag in these examples, which results in the storefront’s default localization. The storefronts that Apple Music is available in and their supported localizations can be found by accessing the storefronts reference endpoint. More detail can be found in the Apple Music API documentation.

Here's a look at making a GET request for a playlist. This returns a resource collection response with a "data" array containing the playlist resource. Resource objects indicate the identity of the content with an ID value and type. The combination of ID and type represent the unique identity of a resource. The href value indicates the location in the API where the resource may be fetched. In this case, note the location is the same as the path we requested. The metadata values for the content are found in the resource's attributes map. Direct connections to other resources, such as this playlist curator and tracks, are found in the relationships map.

Here is a closer look at the attributes map, which contains the metadata values for the playlist. I'll walk through an example of using some of these attributes in the widget on the right, which uses the playlist's name, curator name, and description attributes. playParams is a common attribute on many resource types that indicates when the content is available to stream for subscribers. This can be used to determine if play control should be enabled, as content without playParams is not available for playback. Artwork is another common attribute for many resource types that contains values for the maximum width and height for the image, alongside a url where the image can be loaded from.

At Apple, developer feedback is very important and helps us improve our APIs and services for everyone. This year, we're happy to announce the addition of one of our most requested features. Artist artwork is now available in Apple Music API, making plain silhouettes a thing of the past. All new and existing apps can add support for these images by looking for the artwork attribute added to artist resources. Artist artwork can be loaded the same way as artwork for other content types. Here is an abbreviated example of an artwork url for the playlist we were looking at earlier. Artwork urls contain "w," width and "h," height tokens, highlighted in blue. To load artwork using this URL, replace these tokens with the desired resolution for your display. Since playlist artwork is square, I will use the same resolution for both width and height. Here is an example of requesting a resolution of 400 by 400, at 300 by 300, and at 200 by 200. The images scale for display at each resolution, and the file sizes are reduced for smaller images.

All resource types have a set of default attributes that represent the common or basic metadata for that resource. Some resources have additional attributes that may be fetched, known as "extended attributes." These extended attributes can be requested by using the extend query parameter. For instance, tracks on Apple Music playlists are either songs or music videos. If you'd like to know the types of tracks a playlist contains, you can request the trackTypes extended attribute. Extended attributes appear in the resource’s attributes map alongside their default attributes. If a playlist's tracks are music videos rather than songs, perhaps you would customize the play button to inform the viewer.

Taking a look now at the relationships map shows a couple of direct connections from this playlist to other resources. Many resources have automatic relationships that will be returned when requesting some content directly. The automatic relationships for a playlist are its curator and tracks. Relationships are named to indicate what the connection is, such as the curator for this playlist. They have an href location where the relationship may be fetched directly and a data array for the related resource collection. For playlists, the curator relationship is automatically related, meaning only the identity of the related resources will be present. This allows for easily linking to this resource using its identity or href. Since a playlist already contains the curator's name as an attribute, there may be no need to include other metadata for the related curator resource. The identity of the resource could be used to make the curator name a link, letting people navigate to the curator to discover additional content if they wish. If you want to show additional information for the curator with the playlist, such as its artwork, you will need to fetch the curator's metadata. Use the include parameter to specify the relationships you want related resource metadata for. Some resource types have additional relationships not included by default that can also be requested with this parameter. Note that including relationships can increase the size of responses and negatively impact the speed of your app. Many useful values that may be desired from related resources can be found directly as attributes on the original resource. For the best performance, we recommend including only the relationships and metadata needed in the response. Detailed information for resource types and their available attributes and relationships can be found in the Apple Music API documentation. For more about extended attributes, relationships, and special relationships called views, watch the session “Explore the catalog with the Apple Music API.” Revisiting the relationships for the example playlist, the tracks for the playlist are automatically included, meaning the attribute metadata for the related track resources appear in the response. The attributes for the related tracks can be used to display a track list for the playlist using their artwork and other metadata shown in the widget on the right. In the previous section, I showed an example of fetching a playlist resource from the catalog with its tracks. In this section, I'll explain how to handle relationships with a large number of resources. The related resources for a relationship appear in its data array. When the number of related resources is small, all of the resources will appear in a single response. Relationships with more related resources than appear in a single response must be fetched in multiple parts called pages.

I'll use the tracks relationship for a large playlist as an example. Only the first 100 tracks of a playlist are included by default. If a playlist has more than 100 tracks, then the additional tracks must be fetched in subsequent pages. Here is an example response for a playlist with over 100 tracks. The href and resource collection data for the tracks relationship appear in the response as was seen earlier. Since this playlist has more tracks than were included in the response, a next location appears as a sibling to the data. The next location represents where the remaining resources in the collection can be fetched. Fetching the next location makes a direct relationship fetch and returns the relationship's resource collection data starting from the provided offset. The default limit for the relationship will apply to each page. You may select your own page size by supplying a limit parameter. The page size limit can be between one and the specific relationship's maximum page size, which can be found in the documentation. If the resource collection for the relationship contains additional resources past the ones returned in the page, a next location will continue to appear as a sibling to the data. When the resource collection is exhausted, a next location will not be present. Note that next locations do not reflect the selected page size for the request. You will need to supply a limit parameter on each request if you wish to use a different page size than the default. Always use the next location from the response to page over resource collections. Trying to calculate your own offset can result in issues with invalid locations or duplicate results. In the next section, I will show how to search fof content in the Apple Music catalog using Apple Music API. Apple Music API provides functionality to find content in the catalog using a search term. A search request resembles a catalog resource request with /search as the location and the search term as a parameter. You can specify which content types you're interested in with the types parameter and the maximum number of results to include for each type using a limit. When more results are found past the requested limit, pagination can be used to continue the search. Here's the response to a search for albums and songs with the term “pop." The search endpoint returns a response with a results object containing a group for each requested type with matching content. For this request, matches were found for albums and songs.

The response also includes a meta object containing a recommended order for the result groups based on relevancy. This may be helpful if you're building a search experience that handles multiple content types at once. Each result group has and href where the results were fetched from and a resource collection data array containing the matching resources of the relevant type for the search term. If more matches for a result group are available, the group will contain a next location where additional matches may be fetched. Requesting the next location returns more results for the selected type starting from the offset. In the last section, I’ll discuss accessing personalized features in Apple Music API.

Apple Music API and MusicKit provide access to features personalized to a specific user. These features let you add support for subscribers to view and search for content in their Apple Music library, including the ability to add content they enjoy and create new playlists. Personalized Recommendations can be surfaced based on individual music tastes. And you can let people rediscover music they've been listening to recently to pick up where they left off or provide entirely new experiences.

Personalized features are available for people with an active subscription to Apple Music. To support these features, you must first authenticate the person with your app using MusicKit and request permission to access their music data. When permission is granted, a Music User Token will be available. This token is added to Apple Music API requests in the music-user-token header and is used to authenticate access to personalized data.

A Music User Token is specific to your app and the device the user authenticated on. This token must not be shared across devices, as permission is granted for a single device at a time. A token may become invalid based on changes to a person’s subscription or password, or if they revoke access to your app. It may also expire with time. Authentication can be refreshed by prompting them to sign back in and grant permission for your app. Note that this token is managed automatically by MusicKit on Apple platforms and MusicKit on the Web. Please see the documentation for the framework you're using for more details. In today's session, I showed how you can integrate Apple Music into your apps using MusicKit and Apple Music API, a quick look at the platforms with support for MusicKit client frameworks, and how to use Apple Music API to access and find content in the catalog, and some personalized features available for subscribers. For more on this year's updates to MusicKit on Apple platforms, check out the session "Explore more content with MusicKit.” Thank you for watching, and we hope you enjoy the rest of this year's WWDC.