Expanding automation with the App Store Connect API

Hello and welcome to WWDC.

Hello. Welcome to "Expanding Automation with the App Store Connect API." My name is Geoff Coffey. I'm an engineer on App Store Connect. Today, we're gonna look at some new capabilities coming to the App Store Connect API later this year.

We introduced this API two years ago at WWDC and since then, the response from our users has been really great. We love seeing and hearing about how you use the API to streamline your app development and TestFlight programs. For the first release, we focused on things you do repeatedly in App Store Connect. Things like managing the users on your team, creating provisioning profiles, adding and removing beta testers and downloading your sales and financial reports. Since you do these things over and over again, we gave you the tools to automate them so you have more time to focus on your apps. Here's where we started two years ago. But there are important parts of your app development workflow that aren't covered by the API. I'm excited to announce two powerful new extensions coming to the App Store Connect API later this year. First, we're adding a comprehensive App Metadata API so you can manage your presence on the App Store, and the new Power and Performance Metrics and Diagnostics API lets you programmatically access the same aggregate data that drives the Power and Performance analysis tools in Xcode. This is a huge update to the App Store Connect API. We've added over 200 new endpoints, more than doubling the size of the API in all. You can manage app information like your app categories, global availability, primary locale and license agreements. You can make new versions or add new platforms, upload app previews and screenshots and add and update localized information like your app name, description and keywords, and so much more. The API has complete coverage of app version metadata so you can do everything from creating a new version through to submitting for App Review. I do want to note that you'll still need to use the App Store Connect website to manually release your app and to configure in-app purchases and Game Center. With so much new to discover and code against, we want to make the process of using the API as easy as possible. So, we're also making a full OpenAPI specification file available to you to download. If you're not familiar with OpenAPI, it's the open standard version 3 of the popular Swagger format. You can view it in the Swagger-UI for a quick API reference, or better yet, feed it into a code generator to make bootstrapping your API integration in almost any language faster and easier. We've also improved the documentation. Of course, all the new endpoints are documented, now with clearer complete request and response examples. We've added several new explanatory articles on topics like rate limiting and file uploads.

And we're providing downloadable sample code that demonstrates important API concepts like creating and signing authentication tokens, interacting with API responses and using the new asset upload APIs.

So, let's take a look at what you can do with the new App Metadata API. This is my app, Forest Explorer. I've been hard at work on a new version, and I'm ready to submit this version to the App Store. Let me show you how I would do this using the new API.

We're going to focus on five areas. We'll create a new version, set pricing, update the app metadata, associate a build with that version and then submit that new version for App Review. Let's start by creating a new version of our app.

In App Store Connect, you do this on the App page using these links here in the sidebar. I can make a new version of my iOS app, or I can add a macOS or tvOS version. The API supports the same operations. In the API, we have a resource called Apps. You have one of these for each of your apps.

And each app has a relationship to App Store Versions. They have a platform, iOS, tvOS or macOS, and they have a version string, which is the version number that you want to show in the App Store. So all we need to do is create a new App Store Version. When we do that, we'll link it to our app by ID. So really, the first thing we need to do is look up our app identifier. We can do this with the API. I'm going to do a GET on v1/apps, and I'm going to filter by bundleID since that's a good way to find exactly the app I'm looking for. If I send that request, I get a successful 200 response. The response contains the app resource, and here we see the app identifier. In the App Store Connect documentation, you sometimes see this ID called the Apple ID of your app. We'll take note of this ID and we're ready to make a new version. We do a POST to v1/appStoreVersions, we supply the platform and our new versionString and we include a relationship link to the app. And here's where we use that App ID we just looked up. I send this request, and I get a 201 CREATED response. This tells us App Store Connect has created this new version. If we were to log in to App Store Connect right now, we'd see this version in the sidebar. And here in the response, we see the identifier App Store Connect has assigned to this version.

Now we want to set pricing and availability for our app.

On the App page in App Store Connect, you start by clicking Pricing and Availability here in the sidebar which takes us to the Pricing and Availability page. And in particular, today we're going to look at the Price Schedule. Now, I'm not going to show it today, but you can also use the API to manage your app preorders and your app's global availability. So, how does pricing fit into the API resource model? Once again, we start with the Apps Resource. It has another relationship to a resource called App Prices. Each App Price has a startDate. For the current price, this will be null. But this is a Price Schedule, so we may have multiple planned future price changes. In that case, our app will have multiple prices, and each additional price will have a startDate, which is the date that price takes effect around the world. Each App Price also has a Price Tier. These are exactly the same tiers you're familiar with from App Store Connect. The free tier, Tier 1, which is 99 cents in US dollars, and so on. To select a tier in App Store Connect, you would normally refer to All Prices and Currencies page. Let me show you. Back on the Pricing and Availability, we click All Prices and Currencies here, and we see a list of prices like this. It has tiers down the side and App Store territories across the top, and for each tier and territory, we see individual price points. Each price point has two values: the price the customer pays for the app in the currency relevant to that territory, and the proceeds you will earn for each sale. Back on the resource model, the price tier here is actually a relationship to another set of resources. These gray resources are read-only reference data, the exact same data you just saw on the All Prices and Currencies page. Each price tier contains a collection of price points, one point for each app store territory. And these price points tell you the customer price and the proceeds. Okay, with all of that in mind, let's use the API to look at the current Price Schedule for our app. We do a GET on v1/apps and then the ID of our app, and then the prices relationship, and I'm also going to include the related priceTier so we can see that in the response. I execute this request and I get back a list of prices. In this case, we have just one price. The startDate is null, meaning it's currently in effect, and here's the priceTier relationship where I can see it's linked to Tier 1. Let's compare this JSON data to what we see in App Store Connect. If we look closer at the Price Schedule, we can see the same basic information. We have one price, it's currently in effect, at Tier 1.

Now, suppose we want to run a special pricing promotion for our app. Starting on June 29th, for one week, let's give our app away for free. In other words, we want the Price Schedule to look like this.

Now we have three prices. Tier 1 is in effect until June 29th. Starting on June 29th, we'll switch to the free tier. And then a week later, on July 6th, we want it to change back to Tier 1. Let's make this Price Schedule change using the API.

Although we're adding three prices, I want to make a single atomic change to the overall Price Schedule. So, we're going to make a PATCH request against the app itself. We're not changing any app attributes, so we leave the attribute section off, but we are changing the prices relationship. Now, if you're familiar with App Store Connect, you know that we would normally add the IDs of the resources we want to associate with the app right here. But in this case, the app price resources don't actually exist yet. We need to create them and attach them to the app, all in a single request. Since the prices don't exist, they don't have IDs, so let's assign them temporary IDs for now. We have three prices, so we need three temporary IDs. I'll use new-price-1, new-price-2 and new-price-3. You can use any values you want for these temporary IDs. The important things is I'm using this syntax with a dollar sign and braces around the ID. That serves as a signal to the API that this is a temporary ID for a resource that doesn't exist yet, one that we will be defining in this same request. Now we need to define those new app price resources. Here's the first one. We give it the first temporary ID of new-price-1, again with that dollar sign syntax. It has a startDate of null, meaning this is the price we want right now. You can also just leave the startDate off in this scenario. It would do the same thing. And finally, we link it with Tier 1. Next, we define the second price. It looks like this. It has an ID of new-price-2, a startDate of June 29th, and we link it to Tier 0, the free tier.

And finally, we define new-price-3 with a date of July 6, and we'll switch back to priceTier 1. Now bear in mind, we haven't sent any requests for this Price Schedule change. We're still building the JSON payload for that single atomic request I talked about before. Here's the request we were working on. And now we need to add the prices we just defined into this request. We add an "included" section to our request entity, and then we take those three new prices and insert them into this included array. The final payload looks like this, or at least as much of it as I can fit on the screen. Now, the order of the resources in the included array doesn't matter. The important thing is that these temporary IDs up here match one-to-one with the temporary IDs down here.

When we send this request, App Store Connect will create these three prices, assign them real IDs and link them to our app, all in one atomic operation. Let's send it. We get back a 200 response, and our new Price Schedule is now applied. Now, it's important to note that price changes and available territory changes go to the App Store right away. If your app is already released, the changes will take effect immediately. They will not wait for your next version to go through App Review and then be released. So when experimenting with the API, be sure not to test on live apps.

Now let's talk about editing your app metadata. This is a really big area in the API with lots of endpoints, so let me show you around first.

Back on our Version page, I can click App Information, and that takes me to a page where we see app-level information including the localized app name, subtitle and privacy policy and the App Store categorization. And if we click here on our version, we see version-level information. This is metadata that changes on a platform-by-platform basis like screenshots, promotional text and keywords. The API resource model works in much the same way. Here's what we've seen so far. The app also has a relationship to a resource called App Info. This is where you'll find app-level information like your App Store categorization. And some of that app information is localized, so each App Info has a relationship to multiple App Info Localizations, one for each locale.

Here you'll find attributes like app name, subtitle and privacy policy. And, of course, there's localized data at the version level too. We call this resource the App Store Version Localization. The version has one of these for each locale as well. Let's flip back to App Store Connect and look a little closer at our version page. I'm looking at the US English localization here, and if we look closer at screenshots and app previews, we see we have multiple display types like the 6.5-inch iPhone, the 5.5-inch iPhone or the 12.9-inch iPad Pro. Within each display type, we can upload up to three previews and up to ten screenshots. All of this is modeled in the API through resources and relationships as well. The version localization has a relationship to multiple app screenshot sets, one for each display type. The localization also has multiple app preview sets. And finally, each screenshot set has a relationship to multiple screenshots, and each preview set to multiple previews. There's a lot more to app version metadata, but these are the major resources we'll talk about today.

So let's say we want to upload a 6.5-inch iPhone app preview in the US English localization to promote my new version.

In other words, let's find the US English localization, get the app preview set and add a new preview to it.

Every version has at least one localization: the one in your app's primary locale. We can fetch that localization for our versions like this. We issue a GET request to the appStoreVersionLocalizations URL for our version ID. The response includes all of our localizations including this one for US English. And down here we see the related URL for the appPreviewSets. Let's GET this URL, and we get back an empty data array. This tells us we don't have any app preview sets for this localization. So, let's add one. As you probably would guess, we POST to v1/appPreviewSets. We'll use a previewType of IPHONE_65, that's the 6.5-inch iPhone, and we link it to the localization we were just looking at by ID. We send this request, and the preview set has been created. Now we're ready to add an app preview.

We send this request, and the preview set has been created.

But a preview is more than just some attributes and relationships. You have a video file that you need to upload to App Store Connect. This is a type of API interaction you've never seen before in the App Store Connect API, so let's step back a minute and look at how this works. App previews are just one type of file you can upload using the API. You could also upload screenshots, App Review attachments and GeoJSON routing app coverage files. But whatever you're uploading, the fundamental problem is the same: you have this file on your disk, we call it an asset, and you want to get it up to App Store Connect. But the Internet is standing in the way. Our asset upload process is a multi-step process designed to ensure that you can get even large video files into App Store Connect as quickly as possible, and get them there reliably even if the Internet connection isn't always perfectly reliable.

It works like this. First, you create a reservation. Then you upload the actual assets, possibly in multiple parts. Then you commit the asset. And finally, you check for errors. Let's try it out.

You create an app preview reservation by doing a POST to v1/appPreviews.

And you tell App Store Connect the name of the file you'll be uploading and the file size in bytes. You link it to the preview set we just created, and App Store Connect reserves a place for this preview. It uses the file size to create a set of upload operations. For small assets, this is simple: just an HTTP PUT operation to upload the data to our servers. But for large assets, we will send you back multiple operations. Each operation includes the same properties: an HTTP method, a URL, a length in bytes, an offset in bytes and a set of request headers. You then take these operations and use the information in them to split your asset into multiple parts: one part for each operation.

You'll use the length and offset values in each operation to determine the range of bytes in the file associated with each part. Note that you should always be prepared to receive multiple operations. We may use various factors to decide how many operations are needed. So, an asset that you upload in just one part today might require multiple parts tomorrow. So your code should always expect the possibility of multiple upload operations.

Okay. With our asset split into parts, we're ready for step number two. Using the method, URL and request headers in each upload operation, you upload the associated part. You can do this one at a time or you can upload multiple parts at once.

You can upload these parts in any order. It doesn't matter at all. Of course, sometimes the upload will fail. That's okay. Just try the part again. If one part fails, there's no need to re-upload the other parts. Just keep trying until all of the parts are up. Once they are, you're ready for step number three, which is to commit the asset. To do this, you PATCH the preview URL and mark the preview uploaded by setting its uploaded attribute to true. You also need to provide an MD5 checksum of the original source file. App Store Connect will use this checksum to make sure the multiple parts were divided and uploaded correctly. We send this request. App Store Connect then reassembles the asset, validates the checksum, checks the file integrity, like, is this actually a video file, and checks various metrics like video length, dimensions and audio track. If everything looks good, the asset is marked complete, and your app preview is ready to submit for review. Bear in mind that asset processing is asynchronous. For large assets, it may take some time. You can use the API to re-fetch an asset at any time to check on its status.

If we fetch the app preview, we can check its state attribute right here. Once validation is successful, the asset state will switch to COMPLETE. If anything goes wrong, the state will instead change to FAILED and the errors array will tell you what went wrong so you can delete the asset, fix the problem and re-upload. We looked closely at app previews and a few other app metadata-related resources today, but we only scratched the surface. There's lots more metadata you can manage and edit with the API. Be sure to check out the new App Metadata section in the documentation. It has a complete list of API endpoints related to app and version metadata. Now let's look at adding a build to our new version. In App Store Connect, you do this on the version page in the Build section right here. Where does that fit into our resource model? Right here. The App Store version has a relationship to its associated build. Of course, you don't actually create builds with the API. You create your builds with Xcode and you upload them using Xcode or using Transporter. So presumably, the build is already in App Store Connect. We just need to look up its ID and associate it with the version. This is probably starting to look familiar to you now. We GET v1/builds. I'm gonna filter by the app ID, the pre-release version number and the build version number. And from the response, I'll grab the build ID. Now we can PATCH the build relationship on our new version with that build ID. We send it in and we get back this 204 NO CONTENT response. Since this was a relationship update, there's no resource data to return. So, this is a successful response message telling us the build and version IDs were valid, and they're now correctly associated with each other.

With metadata complete and a build added, we're ready to submit for Review.

In App Store Connect, this is a three-step process. First, we provide the contact info, demo account and any notes that App Review may need. Then, if necessary, we can upload attachments. And finally, we click submit for review. In the API, we once again start with the App Store version. It has a relationship to App Store Review Details, where you can add information for App Review. This in turn has multiple App Review attachments. These work just like app previews, allowing you to upload files to App Store Connect.

To add App Review details to a new version, just POST to v1/appReviewDetails, provide the necessary information and associate it with the version. And we're good. App Review details are now attached to our version. If you've already added App Review details, you can edit them using a PATCH instead. You can edit this information as often as you want up to the point where you actually submit for review.

Now let's see how we do that. How do we actually click that Submit for Review button using the API? Once again, we have another resource. It's called the App Store Version Submission. To submit a version to the App Store, we just create one of these. We POST to v1/appStoreVersionSubmissions, link it to our version and send the request. And that's it. Our version is on its way to App Review. If we made a mistake and want to pull this app back before it gets reviewed, we can just delete this App Store Version Submission resource.

Of course, if our version isn't ready yet, say we forgot to add screenshots, then creating a submission will fail with a 400 response and that response will contain error messages explaining what we need to fix. And remember, if your version requires in-app purchases or Game Center configurations, you'll need to set those up in the App Store Connect website before you submit for review. That's the App Metadata API. Hopefully this gives you a sense of how these API resources all fit together. Using them, we were able to successfully create a version, provide all the necessary App Store information and send it in to App Review. If we have auto-release enabled, our app will go to the App Store as soon as review is complete. You can also release manually in App Store Connect on the web or on iOS if you prefer.

Now let's turn to the new Power and Performance Metrics and Diagnostics API. This is the Power and Performance view in Xcode. It helps you monitor app performance indicators like memory usage, launch time, hang rate, disk writes and battery consumption using data collected from real customer sessions. You can access this same information using the API. I'm going to give you a high level view of how to access this data and how it fits into the larger API resource model. But we actually have a whole session devoted to this feature where you'll learn more about this new API, including how to interpret the response data and find insights into your app's behavior. So be sure to check out the "Power and Performance App Store Connect API" session video as well.

You can get performance metrics for recent versions of your app by requesting the perfPowerMetrics relationship off the app URL. The metrics data uses a custom media type, so you need an appropriate Accept header as well. That will get you metrics for recent versions of your app, but you can also fetch metrics for a particular build using the perfPowerMetrics relationship off the build URL instead. Either way, once we send this request, we get back a successful response with a structured set of metrics data. In this, I can see that the first set of metrics are HANG metrics and the first data set is the hang rate expressed in seconds per hour.

Check out that other session to see the rest of this response and learn how to interpret this data. But there are two more endpoints I want to show you. For Disk Writes in particular, once you've identified a problem spot, you can view diagnostic information, including call stacks, to help pinpoint the source of potential problems. In Xcode, we show you a list of diagnostic signatures. These are just places in your app where you do disk writes. These signatures are sorted by percentage contribution to total disk writes, so the biggest contributors are up at the top. And for each diagnostic signature, you can view the actual call stack and additional diagnostic details. You can get this same information using the API. Once again, we start with the build URL and we fetch its new diagnosticSignatures relationship. Let's get it. And the API responds with a list of diagnostic signatures. These are standard App Store Connect API resources. They have a signature attribute. This identifies where in your run time the disk write takes place and a weight which tells you how much this signature contributes to total writes. Each signature also has a relationship to its log data. If we take this link and once again use that custom media type, we get back diagnostic data. In addition to app information and total disk writes, you'll find detailed call stack information in this response.

And that's the App Metadata and Power and Performance Metrics and Diagnostic APIs. Together these represent a big update to the App Store Connect API. We look forward to seeing how you take advantage of them. Thank you.