Applaud

Applaud is a Python client library for accessing App Store Connect API, generated by Applaudgen.

Features

• Support App Store Connect API latest version 1.6
• Support filter, fileds, include, limit, sort, exists and other query parameters
• All endpoints / paths are implemented, include, but not limited to: App Information, TestFlight, Users and Roles, Sales and Finances
• Pythonic, all camelCase schema fields are represented as snake_case class attributes
• Embrace Python type hints
• Use Python Requests to hanlde HTTP sessions
• ErrorResponse can be catched as exception

Installation

Install with pip:

pip install applaud

Install with Poetry:

poetry add applaud

Install with Pipenv:

pipenv install applaud

Usage

Calls to the API require authorization, so before we get started, you obtain keys to create the tokens from your organization’s App Store Connect account. See Creating API Keys for App Store Connect API to create your keys and tokens.

Connection

Connection is the core class of Applaud, it holds a connection between client and remote service, generate a new token before it expires.

fromapplaud.connectionimportConnection# Create a connection object using API keysconnection=Connection(APPSTORE_ISSUER_ID, APPSTORE_KEY_ID, APPSTORE_PRIVATE_KEY)

In most of cases, all tasks you'd like to perform on remote service should be initiated from a Connection object. Connection has a bunch of functions help you create …Endpoint objects:

# Return an AppListEndpoint objectconnection.apps()

Endpoint

A …Endpoint class encapsulates all operations you can perform on a specific resource. For example, this snippet fetches first two (sort by app name) apps that "ready for sale" and have game center enabled versions:

# Return an AppsResponse objectconnection.apps().filter(
app_store_versions_app_store_state=AppStoreVersionState.READY_FOR_SALE
).exists(
game_center_enabled_versions=True
).limit(
2
).sort(
name: SortOrder.ASC
).get()

…Endpoint.get()

The get() operation initiates a HTTP GET request on the endpoint's path. For example, the URL of List Apps service endpoint is:

GET https://api.appstoreconnect.apple.com/v1/apps

The corresponding code in Applaud:

# Return an AppsResponse objectresponse=connection.apps().get()
forappinresponse.data:
print(f'{app.attributes.name}: {app.attributes.bundle_id}')

Unlike other operations (create(), update() and delete()), get() operation can be chained by query parameters functions:

filter()

You use filter() function to extract matching resources. For example:

filter[bundleId] Attributes, relationships, and IDs by which to filter.
[string]

The corresponding code in Applaud:

response=connection.apps().filter(
bundle_id="com.exmaple.app1"
).get()
# orconnection.apps().filter(
bundle_id=["com.exmaple.app1", "com.exmaple.app2"]
).get()
forappinresponse.data:
print(f'{app.attributes.name}: {app.attributes.bundle_id}')

include()

You use include() function to ask relationship data to include in the response. For example:

 include Relationship data to include in the response.
[string] Possible values: appClips, appInfos, appStoreVersions,
availableTerritories, betaAppLocalizations,
betaAppReviewDetail, betaGroups, betaLicenseAgreement,
builds, ciProduct, endUserLicenseAgreement,
gameCenterEnabledVersions, inAppPurchases, preOrder,
preReleaseVersions, prices

The corresponding code in Applaud:

response=connection.apps().include(
AppListEndpoint.Include.BETA_LICENSE_AGREEMENT
).get()
# orresponse=connection.apps().include(
[AppListEndpoint.Include.BETA_LICENSE_AGREEMENT, AppListEndpoint.Include.PRICES]
).get()

fields()

You use fields() function to ask fields data to return for included related resources in a get() operation. Related resources specified in fields() function MUST be included explicitly in include() function, otherwise, the remote service may not return the fields data that you expect. For example:

fields[betaLicenseAgreements] Fields to return for included related types.
[string] Possible values: agreementText, app

The corresponding code in Applaud:

connection.apps().include(
AppListEndpoint.Include.BETA_LICENSE_AGREEMENT
).fields(
beta_license_agreement=[BetaLicenseAgreementField.AGREEMENT_TEXT, BetaLicenseAgreementField.APP]
).get()

limit()

You use limit() function to restrict the maximum number of resources to return in a get() operation. For example:

 limit Number of resources to return.
integer Maximum Value: 200

The corresponding code in Applaud:

# Return a response contains 10 apps at mostconnection.apps().limit(10).get()
# Raise a ValueError exception, the maxinmu allowed value is 200connection.apps().limit(400).get()

You can also included limit the number of related resources to return, as in fields() function, you MUST also specify the related resources explicitly in include() function. For example:

limit[appStoreVersions] integer
Maximum Value: 50

The corresponding code in Applaud:

# All returned apps have 5 related app store version at mostconnection.apps().include(
AppListEndpoint.Include.APP_STORE_VERSIONS
).limit(app_store_versions=5).get()
# Raise a ValueError exception, the maxinmu allowed value is 50connection.apps().include(
AppListEndpoint.Include.APP_STORE_VERSIONS
).limit(app_store_versions=100).get()

By leverage limit() function with sort() function, your script can be more responsive.

sort()

You use sort() function to sort the returned resources by attributes in ascending or descending order. For example:

 sort Attributes by which to sort.
[string] Possible values: bundleId, -bundleId, name, -name, sku, -sku

The corresponding code in Applaud:

connection.apps().sort(name=SortOrder.ASC, bundleId=SortOrder.DESC).get()

exists()

exists() is a special type of filter – filter by existence or non-existence of related resource. For example:

exists[gameCenterEnabledVersions] [string]

The corresponding code in Applaud:

connection.apps().exists(game_center_enabled_versions=True).get()

…Endpoint.create()

The create() operation initiates a HTTP POST request on the endpoint's path. For example, the URL of Create an App Store Version service endpoint is:

POST https://api.appstoreconnect.apple.com/v1/appStoreVersions

The corresponding code in Applaud:

request=AppStoreVersionCreateRequest(
data=AppStoreVersionCreateRequest.Data(
relationships=AppStoreVersionCreateRequest.Data.Relationships(
app=AppStoreVersionCreateRequest.Data.Relationships.App(
data=AppStoreVersionCreateRequest.Data.Relationships.App.Data(
id='com.exmaple.app1'
)
)
),
attributes=AppStoreVersionCreateRequest.Data.Attributes(
version_string='1.6',
platform=Platform.IOS,
copyright=f'Copyright © 2021 Codinn Technologies. All rights reserved.',
release_type=AppStoreVersionReleaseType.AFTER_APPROVAL
)
)
)
# Return an AppStoreVersionResponse objectreponse=connection.app_store_versions().create(request)
version=response.dataprint(f'{version.version_string}: {version.created_date}, {version.app_store_state}')

…Endpoint.update()

The update() operation initiates a HTTP PATCH request on the endpoint's path. For example, the URL of Modify an App Store Version service endpoint is:

PATCH https://api.appstoreconnect.apple.com/v1/appStoreVersions/{id}

The corresponding code in Applaud:

# Get the version id created in previous exampleversion_id=version.data.id# Update version's informationrequest=AppStoreVersionUpdateRequest(
data=AppStoreVersionUpdateRequest.Data(
id=version.data.id,
attributes=AppStoreVersionUpdateRequest.Data.Attributes(
version_string='1.6.1',
platform=Platform.IOS,
copyright=f'Copyright © 2022 Codinn Technologies. All rights reserved.',
release_type=AppStoreVersionReleaseType.AFTER_APPROVAL
)
)
)
# Return an AppStoreVersionResponse objectreponse=connection.app_store_version(version_id).update(request)
version=response.dataprint(f'{version.version_string}: {version.copyright}, {version.app_store_state}')

…Endpoint.delete()

The delete() operation initiates a HTTP DELETE request on the endpoint's path. For example, the URL of Delete an App Store Version service endpoint is:

DELETE https://api.appstoreconnect.apple.com/v1/appStoreVersions/{id}

The corresponding code in Applaud:

# Get the version id created in previous exampleversion_id=version.data.idconnection.app_store_version(version_id).delete()

Exceptions

…Endpoint.get(), …Endpoint.create(), …Endpoint.update() and …Endpoint.delete() may raise two types of exceptions:

1. HTTP request exceptions raised by Python Requests
2. Remote service returns an ErrorResponse

For the second case, Applaud raises an EndpointException exception, and attaches all ErrorResponse.Error objects in EndpointException.errors attribute.

Some errors are harmless, for example, App Store Connect has no API for you to tell whether a tester has accepted beta test invitation or not. When you trying to resend invitations to testers, you may encounter an ALREADY_ACCEPTED error, it's safe to just ignore such error:

try:
# Send / resend beta test invitationsresponse=connection.beta_tester_invitations().create(…)
exceptEndpointExceptionaserr:
already_accepted_error=Falseforeinerr.errors:
ife.code=='STATE_ERROR.TESTER_INVITE.ALREADY_ACCEPTED':
# silent this erroralready_accepted_error=Truebreakifnotalready_accepted_error:
raiseerr

Caveats

• Query parameters functions (filter(), include, fields …) play a role only when using with …Endpoint.get(). Though there is no side effects if chain it with …Endpoint.create(), …Endpoint.update() and …Endpoint.delete() operations, it is not adviced.