App Store Connect

A Swift library for accessing Apple's App Store Connect API and Enterprise Program API.

import AppStoreConnect
import AppStoreAPI

let privateKey = try JWT.PrivateKey(contentsOf: URL(filePath: "..."))
let client = AppStoreConnectClient(
    authenticator: JWT(
        keyID: "...",
        issuerID: "...",
        expiryDuration: 20 * 60, // 20 minutes
        privateKey: privateKey
    )
)

let apps = try await client.send(Resources.v1.apps.get())
print(apps)

Installation

This project supports Swift 5.9 and higher, and has minimum requirements of iOS 16, macOS 13, tvOS 16, and watchOS 9. It strives to be fully supported for deployment on all other platforms outlined by Swift.org Platform Support page, such as the various Linux flavors and Windows. App Store Connect API version 3.7 and Enterprise Program 1.0 are supported.

The package defines two products: AppStoreConnect and EnterpriseProgram. Each product provides the AppStoreConnect module, which contains the client and authentication logic, and either the AppStoreAPI or EnterpriseAPI modules, respectively. To integrate with App Store Connect, you would add a dependency on the "AppStoreConnect" product. To use the Enterprise Program API, add the "EnterpriseProgram" product as a target dependency instead. Finally, both products can be made dependencies of the same target without significant conflict. See the invite_user sample for a rough example of this.

Swift Package Manager

To use AppStoreConnect in your project, add the following line to the dependencies in your Package.swift file:

.package(url: "https://github.com/aaronsky/asc-swift", from: "1.0.0"),

Then, include "AppStoreConnect" as a dependency of your target:

.target(name: "<target>", dependencies: [
    .product(name: "AppStoreConnect", package: "AppStoreConnect"),
]),

Finally, add import AppStoreConnect to your code to import the client, and import AppStoreAPI to import the API bindings.

Bazel

This project is available on the Bazel Central Registry. Much like other modules there, all that's required to add the dependency is to insert the following line into your MODULE.bazel. Note that this requires your project to be using Bzlmod.

bazel_dep(name = "asc_swift", version = "<version>")

An example of how to set this up can be found in Examples/bzlmod.

Usage

Authentication

Neither the App Store Connect API nor Enterprise Program API have any methods that allow for unauthorized requests. To make it easy to authenticate with App Store Connect, this library offers the aforementioned JWT type to handle signing and rotating JSON Web Tokens automatically when they expire. For example:

import AppStoreConnect

let privateKey = try JWT.PrivateKey(contentsOf: URL(filePath: "..."))
let client = AppStoreConnectClient(
    authenticator: JWT(
        keyID: "...",
        issuerID: "...",
        expiryDuration: 20 * 60, // 20 minutes
        privateKey: privateKey
    )
)

Note

JWT instances are bound to the API they are intended for, as credentials are not portable between teams. The designated default is the App Store Connect API. To use the Enterprise Program API, provide api: .enterpriseProgram as the first argument to the JWT initializer.

You can learn more about creating the necessary credentials for the App Store Connect API at Apple's documentation page via Creating API Keys for App Store Connect API, or the corresponding Enterprise Program API documentation here. All App Store Connect and Enterprise Program APIs are scoped to the credentials of the pre-configured key, so you can't use this API to make queries against the entire App Store.

Handling Errors and Rate Limiting

In many cases where the API would respond with an error, the API will include an ErrorResponse object describing the failure in detail. This object also contains properties that can be used to diagnose the root cause of issues if they are due to malformed requests. If the API responds with an error, AppStoreConnectClient will throw Response.Error.requestFailure for your consideration. This error contains the ErrorResponse returned from the API, the HTTP status code, and the underlying response.

Additionally, Apple imposes a rate limit on all API clients. If the API produces a rate limit error, AppStoreConnectClient will throw Response.Error.rateLimitExceeded for your convenience. This error contains the ErrorResponse returned from the API, a Response.Rate containing call limit and remaining call information, and the underlying response.

For example:

do {
    let apps = try await client.send(Resources.v1.apps.get())
} catch Response.Error.requestFailure(let error, let statusCode, let response) {
    print("Received an error: \(error)")
} catch Response.Error.rateLimitExceeded(let error, let rate, let response) {
    print("Client has exceeded the rate limit")
} catch {
    print("An unexpected error occurred: \(error.localizedDescription)")
}

You can learn more about how to handle errors from the App Store Connect API at Apple's documentation page via Interpreting and Handling Errors. You can learn more about rate limiting at Apple's documentation page via Identifying Rate Limits. Corresponding documentation for the Enterprise Program API can be found here and here, respectively.

Paging Large Data Sets

All requests for resource collections (apps, builds, beta groups, etc.) support pagination. Responses for paginated resources will contain a links property of type PagedDocumentLinks, with "reference" URLs for first, next, and self. You can also find more information about the per-page limit and total count of resources in the response's meta field of type PagingInformation. You typically shouldn't require any of this information for typical pagination.

The most common application for pagination is paging forward from the first "page". For example:

for try await appsPage in client.pages(Resources.v1.apps.get()) {
    print(appsPage)
}

You can also page forward manually using the send(_:pageAfter:) method on AppStoreConnectClient.

Uploading Assets

App Store Connect employs a three-step process to upload assets such as previews, screenshots, and routing coverage files as app metadata. The process can be described from a high level as:

1. Make a reservation for the asset
2. Upload the asset in chunks defined by the API
3. Commit the reservation

The process has several fault points and is outlined in detail on Apple's documentation page, Uploading Assets to App Store Connect. This library includes two examples of how to upload assets, upload_preview and upload_screenshot, as well as one detailed article.

Contributing

This project's primary goal is to cover the entire API surface exposed by the official App Store Connect API and Enterprise Program API. Otherwise, it's being developed to aid in internal application development by the authors. Therefore, until the package's version stabilizes with v1, there isn't a strong roadmap beyond those stated goals. However, contributions are always welcome. If you want to get involved or you just want to offer feedback, please see CONTRIBUTING.md for details.

License

This library is released under the BSD-2 license.

See LICENSE for the full text.

Credits

The technical direction of this library was driven by prior work on asc-go and appstoreconnect, as well as a fully-fledged example produced by @AvdLee et al. in appstoreconnect-swift-sdk. Client design was driven by prior work on buildkite-swift and wanikani-swift. App Store Connect, the App Store Connect API, and the Enterprise Program API are property of Apple.