Applelink
Practical API Recipes for App Store Connect Workflows
Install / Use
/learn @tramlinehq/ApplelinkREADME
Rationale
Applelink is a small, self-contained, rack-based service using Hanami::API, that wraps over Spaceship and exposes some nice common recipes as RESTful endpoints in an entirely stateless fashion.
These are based on the needs of the framework that Tramline implements over App Store. The API pulls its weight so Tramline has to do as little as possible. Currently, it exposes 17 API endpoints.
In Applelink, a complex recipe, such as release/prepare, will perform the following tasks all bunched up:
- Ensure that there is an App Store version that we can use for the release, or create a new one
- Update the release metadata for that release version
- Enable phased releases, if necessary
Similarly a simple fetch endpoint like release/live will give you the current status of the latest release.
Applelink is a separate service that is not reliant on Tramline’s internal state. It can be used in a standalone way, for e.g. from a CI workflow, or a Slack bot that spits out app release information.
Development
Running
bundle install
just start
just lint # run lint
Auth token
All APIs (except ping) are secured by JWT auth. Please use standard authorization header:
Authorization: Bearer <AUTH_TOKEN>
The AUTH_TOKEN can be generated using HS256 algo and the secret for generating and verifying the token is shared between Tramline/any other client and applelink.
These can be configured using the following env variables:
AUTH_ISSUER=tramline.dev
AUTH_SECRET=password
AUTH_AUD=applelink
These values can be set to whatever you want, as long as they are same between the caller and Applelink.
Example code for generating the token can be taken from this file in the Tramline repo.
In addition to the auth token, you also need the App Store Connect JWT token which is documented here.
Internal API
For the development environment, you can generate the above tokens using the following helper API:
curl -i -X GET http://127.0.0.1:4000/internal/keys?key_id=KEY_ID&issuer_id=ISSUER_ID
{
"store_token": "eyJraWQiOiJLRVlfSUQiLCJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJJU1NVRVJfSUQiLCJpYXQiOjE2ODIwNjA1MzYsImV4cCI6MTY4MjA2MTAzNiwiYXVkIjoiYXBwc3RvcmVjb25uZWN0LXYxIn0.-pFtamhBjsNKLr5Z2Ft2tW9H2NojBF1d8RqQBr7nNZF43KUNGMQIPQyp9BCSrFXJop1k7hk7jJstXRJ-WMH_8Q",
"auth_token": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2ODIwNjA1MzYsImV4cCI6MTY4MjA2MTUzNiwiYXVkIjoiYXBwbGVsaW5rIiwiaXNzIjoidHJhbWxpbmUuZGV2In0.HDJJw6o6YK-Jmzpl0Xu4SmlTcGtNeEFI0VIg6fqitdw"
}
This expects the correct env variables to be set for AUTH_TOKEN and the App Store Connect key.p8 file to be present in the Applelink directory along with the relevant KEY_ID and ISSUER_iD being passed to the API.
API
One can also use requests in restclient-mode to interactively play around with the entire API including fetching and refreshing tokens.
Headers
| Name | Description |
|------|-------------|
| Authorization | Bearer token signed by tramline |
| Content-Type | Most endpoints expect application/json |
| X-AppStoreConnect-Key-Id | App Store Connect key id acquired from the portal |
| X-AppStoreConnect-Issuer-Id | App Store Connect issuer id acquired from the portal |
| X-AppStoreConnect-Token | App Store Connect expirable JWT signed using the key-id and issuer-id |
Fetch metadata for an App
<details> <summary><code>GET</code> <code><b>/apple/connect/v1/apps/:bundle-id</b></code></summary>Path parameters
| name | type | data type | description | |-----------|-----------|-------------------------|-----------------------------------------------------------------------| | bundle-id | required | string | app's unique identifier |
Example cURL
curl -X GET \ -H "Authorization: Bearer token" \ -H "X-AppStoreConnect-Key-Id: key-id" \ -H "X-AppStoreConnect-Issuer-Id: iss-id" \ -H "X-AppStoreConnect-Token: token" \ -H "Content-Type: application/json" \ http://localhost:4000/apple/connect/v1/apps/com.tramline.app
Success response
</details>{ "id": "1658845856", "name": "Ueno", "bundle_id": "com.tramline.ueno", "sku": "com.tramline.ueno", "primary_locale": "en-US" }
Fetch live info for an app
<details> <summary><code>GET</code> <code><b>/apple/connect/v1/apps/:bundle-id/current_status</b></code></summary>Path parameters
| name | type | data type | description | |-----------|-----------|-------------------------|-----------------------------------------------------------------------| | bundle-id | required | string | app's unique identifier |
Example cURL
curl -X GET \ -H "Authorization: Bearer token" \ -H "X-AppStoreConnect-Key-Id: key-id" \ -H "X-AppStoreConnect-Issuer-Id: iss-id" \ -H "X-AppStoreConnect-Token: token" \ -H "Content-Type: application/json" \ http://localhost:4000/apple/connect/v1/apps/:bundle-id/current_status
Success response
</details>[ { "name": "Big External Group", "builds": [ { "id": "da720570-cb6e-4b25-b82f-790045a6038e", "build_number": "10001", "status": "BETA_APPROVED", "version_string": "1.46.0", "release_date": "2023-04-17T07:03:01-07:00" }, { "id": "1c4d0eb3-5cec-47f2-a843-949b12a69784", "build_number": "9103", "status": "BETA_APPROVED", "version_string": "1.45.0", "release_date": "2023-04-13T00:09:38-07:00" } ] }, { "name": "Small External Group", "builds": [ { "id": "e1aa4795-0df2-4d76-b899-8ee95fb8589e", "build_number": "10002", "status": "BETA_APPROVED", "version_string": "1.47.0", "release_date": "2023-04-17T10:00:19-07:00" }, { "id": "da720570-cb6e-4b25-b82f-790045a6038e", "build_number": "10001", "status": "BETA_APPROVED", "version_string": "1.46.0", "release_date": "2023-04-17T07:03:01-07:00" } ] }, { "name": "production", "builds": [ { "id": "bf11d7a3-fe1c-4c71-acae-a9dc8af57907", "version_string": "1.44.1", "status": "READY_FOR_SALE", "release_date": "2023-04-11T22:45:25-07:00", "build_number": "9086" } ] } ]
Fetch all beta groups for an app
<details> <summary><code>GET</code> <code><b>/apple/connect/v1/apps/:bundle-id/groups</b></code></summary>Path parameters
| name | type | data type | description | |-----------|-----------|-------------------------|-----------------------------------------------------------------------| | bundle-id | required | string | app's unique identifier |
Example cURL
curl -X GET \ -H "Authorization: Bearer token" \ -H "X-AppStoreConnect-Key-Id: key-id" \ -H "X-AppStoreConnect-Issuer-Id: iss-id" \ -H "X-AppStoreConnect-Token: token" \ -H "Content-Type: application/json" \ http://localhost:4000/apple/connect/v1/apps/com.tramline.app/groups
Success response
</details>[{ "name": "The Pledge", "id": "fcacfdf7-db62-44af-a0cb-0676e17c251b", "internal": true }, { "name": "The Prestige", "id": "2cd6be09-d959-4ed3-a4e7-db8cabbe44d0", "internal": true }, { "name": "The Trick", "id": "dab66de0-7af2-48ae-97af-cc8dfdbde51d", "internal": true }, { "name": "Big External Group", "id": "3bc1ca3e-1d4f-4478-8f38-2dcae4dcbb69", "internal": false }, { "name": "Small External Group", "id": "dc64b810-1157-4228-825b-eb9e95cc8fba", "internal": false }]
Fetch a single build for an app
<details> <summary><code>GET</code> <code><b>/apple/connect/v1/apps/:bundle-id/builds/:build-number</b></code></summary>Path parameters
| name | type | data type | description | |-----------|-----------|-------------------------|-----------------------------------------------------------------------| | bundle-id | required | string | app's unique identifier | | build-number | required | integer | build number |
Example cURL
curl -X GET \ -H "Authorization: Bearer token" \ -H "X-AppStoreConnect-Key-Id: key-id" \ -H "X-AppStoreConnect-Issuer-Id: iss-id" \ -H "X-AppStoreConnect-Token: token" \ -H "Conte
