Practical recipes over the App Store Connect API via Fastlane

Read more about the why in this blog post.

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 13 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

GET /apple/connect/v1/apps/:bundle-id

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

{
"id": "1658845856",
"name": "Ueno",
"bundle_id": "com.tramline.ueno",
"sku": "com.tramline.ueno"
}

Fetch live info for an app

GET /apple/connect/v1/apps/:bundle-id/current_status

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

[
  {
    "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

GET /apple/connect/v1/apps/:bundle-id/groups

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

[{
  	"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

GET /apple/connect/v1/apps/:bundle-id/builds/:build-number

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 "Content-Type: application/json" \
http://localhost:4000/apple/connect/v1/apps/com.tramline.app/builds/9018

Success response

{
"id": "bc90d402-ed0c-4d05-887f-d300abc104e9",
"build_number": "9018",
"beta_internal_state": "IN_BETA_TESTING",
"beta_external_state": "BETA_APPROVED",
"uploaded_date": "2023-02-22T22:27:48-08:00",
"expired": false,
"processing_state": "VALID",
"version_string": "1.5.0"
}

Update the test notes for a build in TestFlight

PATCH /apple/connect/v1/apps/:bundle-id/builds/:build-number

Path parameters

name	type	data type	description
bundle-id	required	string	app's unique identifier

JSON Parameters

name	type	data type	description
notes	required	string	"test the feature to add release notes to builds"

Example cURL

curl -X PATCH \
-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" \
-d '{"notes": "test the feature to add release notes to builds"}' \
http://localhost:4000/apple/connect/v1/apps/com.tramline.app/builds/latest

Fetch the latest build for an app

GET /apple/connect/v1/apps/:bundle-id/builds/latest

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/builds/latest

Success response

{
"id": "bc90d402-ed0c-4d05-887f-d300abc104e9",
"build_number": "9018",
"beta_internal_state": "IN_BETA_TESTING",
"beta_external_state": "BETA_APPROVED",
"uploaded_date": "2023-02-22T22:27:48-08:00",
"expired": false,
"processing_state": "VALID",
"version_string": "1.5.0"
}

Assign a build to a beta group

PATCH /apple/connect/v1/apps/:bundle_id/groups/:group-id/add_build

Path parameters

name	type	data type	description
bundle-id	required	string	app's unique identifier
build-number	required	integer	build number
group-id	required	string	beta group id (uuid)

Example cURL

curl -X PATCH \
-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/3bc1ca3e-1d4f-4478-8f38-2dcae4dcbb69/add_build

Prepare a release for the app

POST /apple/connect/v1/apps/:bundle_id/release/prepare

Path parameters

name	type	data type	description
bundle-id	required	string	app's unique identifier

JSON Parameters

name	type	data type	description
build-number	required	integer	build number
version	required	string	version name
is_phased_release	optional	boolean	flag to enable or disable phased release, defaults to false
metadata	required	hash	{ "promotional_text": "this is the app store version promo text", "whats_new": "release notes"}

Example cURL

curl -X POST \
-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" \
-d '{"build_number": 9018, "version": "1.6.2", "is_phased_release": true, "metadata": {"promotional_text": "app store version promo text", "whats_new": "release notes"} }' \
http://localhost:4000/apple/connect/v1/apps/com.tramline.app/release/prepare

Submit a release for review

PATCH /apple/connect/v1/apps/:bundle_id/release/submit

Path parameters

name	type	data type	description
bundle-id	required	string	app's unique identifier

JSON Parameters

name	type	data type	description
build-number	required	integer	build number

Example cURL

curl -X PATCH \
-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" \
-d '{"build_number": 9018}' \
http://localhost:4000/apple/connect/v1/apps/com.tramline.app/release/submit

Fetch the status of current inflight release

GET /apple/connect/v1/apps/:bundle-id/release?build_number=:build-number

Path parameters

name	type	data type	description
bundle-id	required	string	app's unique identifier

Query parameters

name	type	data type	description
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 "Content-Type: application/json" \
http://localhost:4000/apple/connect/v1/apps/com.tramline.app/release?build_number=500

Success response

{
  "id": "bd31faa6-6a9a-4958-82de-d271ddc639a8",
  "version_name": "1.8.0",
  "app_store_state": "PENDING_DEVELOPER_RELEASE",
  "release_type": "MANUAL",
  "earliest_release_date": null,
  "downloadable": true,
  "created_date": "2023-02-25T03:02:46-08:00",
  "build_number": "33417",
  "build_id": "31aafef2-d5fb-45d4-9b02-f0ab5911c1b2",
  "phased_release": {
    "id": "bd31faa6-6a9a-4958-82de-d271ddc639a8",
    "phased_release_state": "INACTIVE",
    "start_date": "2023-02-28T06:38:39Z",
    "total_pause_duration": 0,
    "current_day_number": 0
  },
  "details": {
    "id": "ef59d099-6154-4ccb-826b-3ffe6005ed59",
    "description": "The true Yamanote line aural aesthetic.",
    "locale": "en-US",
    "keywords": "japanese, aural, subway",
    "marketing_url": null,
    "promotional_text": null,
    "support_url": "http://tramline.app",
    "whats_new": "We now have the total distance covered by each station across the line!"
  }
}

Start a release after review is approved

PATCH /apple/connect/v1/apps/:bundle_id/release/start

Path parameters

name	type	data type	description
bundle-id	required	string	app's unique identifier

JSON Parameters

name	type	data type	description
build-number	required	integer	build number

Example cURL

curl -X PATCH \
-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" \
-d '{"build_number": 9018}' \
http://localhost:4000/apple/connect/v1/apps/com.tramline.app/release/start

Fetch the status of current live release

GET /apple/connect/v1/apps/:bundle-id/release/live

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/release/live

Success response

{
  "id": "bd31faa6-6a9a-4958-82de-d271ddc639a8",
  "version_name": "1.8.0",
  "app_store_state": "READY_FOR_SALE",
  "release_type": "MANUAL",
  "earliest_release_date": null,
  "downloadable": true,
  "created_date": "2023-02-25T03:02:46-08:00",
  "build_number": "33417",
  "build_id": "31aafef2-d5fb-45d4-9b02-f0ab5911c1b2",
  "phased_release": {
    "id": "bd31faa6-6a9a-4958-82de-d271ddc639a8",
    "phased_release_state": "COMPLETE",
    "start_date": "2023-02-28T06:38:39Z",
    "total_pause_duration": 0,
    "current_day_number": 4
  },
  "details": {
    "id": "ef59d099-6154-4ccb-826b-3ffe6005ed59",
    "description": "The true Yamanote line aural aesthetic.",
    "locale": "en-US",
    "keywords": "japanese, aural, subway",
    "marketing_url": null,
    "promotional_text": null,
    "support_url": "http://tramline.app",
    "whats_new": "We now have the total distance covered by each station across the line!"
  }
}

Pause the rollout of current live release

PATCH /apple/connect/v1/apps/:bundle_id/release/live/rollout/pause

Path parameters

name	type	data type	description
bundle-id	required	string	app's unique identifier

Example cURL

curl -X PATCH \
-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/release/live/rollout/pause

Resume the rollout of current live release

PATCH /apple/connect/v1/apps/:bundle_id/release/live/rollout/resume

Path parameters

name	type	data type	description
bundle-id	required	string	app's unique identifier

Example cURL

curl -X PATCH \
-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/release/live/rollout/resume

Fully release the current live release to all users

PATCH /apple/connect/v1/apps/:bundle_id/release/live/rollout/complete

Path parameters

name	type	data type	description
bundle-id	required	string	app's unique identifier

Example cURL

curl -X PATCH \
-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/release/live/rollout/complete

Halt the current live release from distribution

PATCH /apple/connect/v1/apps/:bundle_id/release/live/rollout/halt

Path parameters

name	type	data type	description
bundle-id	required	string	app's unique identifier

Example cURL

curl -X PATCH \
-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/release/live/rollout/halt