From 0a96983fbefbfa7e9e42576a2cd52b0e9d3f08fb Mon Sep 17 00:00:00 2001 From: burakberkkeskin Date: Mon, 26 Aug 2024 14:41:41 +0300 Subject: [PATCH 1/9] added faq for API --- docs/appcircle-api/faq.md | 222 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 docs/appcircle-api/faq.md diff --git a/docs/appcircle-api/faq.md b/docs/appcircle-api/faq.md new file mode 100644 index 000000000..54011ec3d --- /dev/null +++ b/docs/appcircle-api/faq.md @@ -0,0 +1,222 @@ +--- +title: Troubleshooting & FAQ +description: Troubleshooting & FAQ +tags: [api, authentication, personal api token, api token, session token, troubleshooting, faq] +sidebar_position: 5 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Overview + +This section is designed to help you quickly find answers to common questions and provide you with a better understanding of Appcircle server API. + +## Appcircle Server API FAQ + +### How can I check the versions of an app published in the Enterprise App Store and download it? + +After you have successfully [created the Personal API Token](/appcircle-api/api-authentication.md#generatingmanaging-the-personal-api-tokens) from the **root organization**, you can check the versions of an application and download them like in the following example code blocks. + +:::caution +You must create the PAT on the root organization. Requests will fail if you create the PAT from a sub-organization. +::: + + + + + +
+ Click to see the code block. +

+ +```bash +#!/usr/bin/env bash + +set -uo pipefail + +PERSONAL_ACCESS_TOKEN="SuperSecretPatTakenFromRootOrganization==" +API_URL="https://api.appcircle.io" # API URL for Appcircle cloud +AUTH_URL="https://auth.appcircle.io" # AUTH URL for Appcircle cloud +STORE_URL="https://mystore.self.appcircle.io" # Your default or custom store URL on Appcircle cloud. + +echo -e "Authenticating to the $AUTH_URL \n" +TOKEN_JSON_RESPONSE=$(curl -fs -X POST "${AUTH_URL}/auth/v1/token" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "pat=$PERSONAL_ACCESS_TOKEN") +if [[ "$?" != "0" ]]; then + echo "Couldn't authenticate to the $API_URL with the PAT." + echo "Please check your PAT." + echo "If you are a self-hosted Appcircle user, please change the 'API_URL', 'AUTH_URL' and 'STORE_URL'" + exit 1 +fi + +ACCESS_TOKEN=$(echo "$TOKEN_JSON_RESPONSE" | jq -j '.access_token') + +echo -e 'Getting profiles... \n' + +PROFILE_RESPONSE=$( curl -fs "${API_URL}/store/v1/profiles" \ + -H "authorization: Bearer $ACCESS_TOKEN" +) +if [[ "$?" != "0" ]]; then + echo "Couldn't get the Enterprise App Store profiles." + echo "Please check your connection." + exit 1 +fi + +PROFILE_ID=$(echo "$PROFILE_RESPONSE" | jq -r '.[0].id') # Get the first element for test responses. You should filter by ids here for your needs. +echo "Enterprise App Store profile id: $PROFILE_ID" +echo -e "Getting app versions... \n" + +APP_VERSION_RESPONSE=$( curl -fs "$API_URL/store/v1/profiles/$PROFILE_ID/app-versions?suborg=all" \ + -H "authorization: Bearer $ACCESS_TOKEN" +) +if [[ "$?" != "0" ]]; then + echo "Couldn't get versions of the selected Enterprise App Store application." + echo "Please check your connection." + exit 1 +fi + +APP_VERSION_ID=$(echo "$APP_VERSION_RESPONSE" | jq -r '.[0].id') # Get the first element for test responses. You should filter by ids here for your needs. +APP_OS_TYPE=$(echo "$APP_VERSION_RESPONSE" | jq -r '.[0].platformType') # Get the first element for test responses. You should filter by ids here for your needs. +APP_OS="" +APP_OUTPUT_FILE="" +echo "App version id: $APP_VERSION_ID" +if [[ "$APP_OS_TYPE" == "1" ]]; then + APP_OS="ios" + APP_OUTPUT_FILE="app.plist" +else + APP_OS="android" + APP_OUTPUT_FILE="app.apk" +fi +echo "App OS: $APP_OS" # 1 for iOS, 2 for Android. +echo -e "Getting app download link... \n" + +echo "Downloading the app to the $APP_OUTPUT_FILE file." + curl -fs --location "$STORE_URL/api/profile/$PROFILE_ID/appversions/$APP_VERSION_ID/download-update" \ + --header "Authorization: Bearer $ACCESS_TOKEN" \ + -o "$APP_OUTPUT_FILE" +``` + +

+
+ + + + + +
+ Click to see the code block. +

+ +```python +import requests +import sys +import json + +PERSONAL_ACCESS_TOKEN = "SuperSecretPatTakenFromRootOrganization==" +API_URL = "https://api.self.appcircle.io" # API URL for Appcircle cloud +AUTH_URL = "https://auth.self.appcircle.io" # AUTH URL for Appcircle cloud +STORE_URL = "https://mystore.self.appcircle.io" # Your default or custom store URL on Appcircle cloud. + +def main(): + print(f"Authenticating to {AUTH_URL}\n") + try: + token_response = requests.post( + f"{AUTH_URL}/auth/v1/token", + headers={"accept": "application/json", "Content-Type": "application/x-www-form-urlencoded"}, + data={"pat": PERSONAL_ACCESS_TOKEN} + ) + token_response.raise_for_status() + except requests.exceptions.RequestException as e: + print(f"Couldn't authenticate to {API_URL} with the PAT.") + print("Please check your PAT.") + print("If you are a self-hosted Appcircle user, please change the 'API_URL', 'AUTH_URL', and 'STORE_URL'") + sys.exit(1) + + access_token = token_response.json().get("access_token") + + print('Getting profiles...\n') + try: + profile_response = requests.get( + f"{API_URL}/store/v1/profiles", + headers={"authorization": f"Bearer {access_token}"} + ) + profile_response.raise_for_status() + except requests.exceptions.RequestException as e: + print("Couldn't get the Enterprise App Store profiles.") + print("Please check your connection.") + sys.exit(1) + + profiles = profile_response.json() + if not profiles: + print("No profiles found.") + sys.exit(1) + + profile_id = profiles[0].get("id") + print(f"Enterprise App Store profile id: {profile_id}") + + print("Getting app versions...\n") + try: + app_version_response = requests.get( + f"{API_URL}/store/v1/profiles/{profile_id}/app-versions?suborg=all", + headers={"authorization": f"Bearer {access_token}"} + ) + app_version_response.raise_for_status() + except requests.exceptions.RequestException as e: + print("Couldn't get versions of the selected Enterprise App Store application.") + print("Please check your connection.") + sys.exit(1) + + app_versions = app_version_response.json() + if not app_versions: + print("No app versions found.") + sys.exit(1) + + app_version_id = app_versions[0].get("id") + app_os_type = app_versions[0].get("platformType") + app_os = "ios" if app_os_type == "1" else "android" + app_output_file = "app.plist" if app_os == "ios" else "app.apk" + + print(f"App version id: {app_version_id}") + print(f"App OS: {app_os}") # 1 for iOS, 2 for Android. + print("Getting app download link...\n") + + print(f"Downloading the app to the {app_output_file} file.") + try: + download_response = requests.get( + f"{STORE_URL}/api/profile/{profile_id}/appversions/{app_version_id}/download-update", + headers={"Authorization": f"Bearer {access_token}"}, + stream=True + ) + download_response.raise_for_status() + with open(app_output_file, "wb") as f: + for chunk in download_response.iter_content(chunk_size=8192): + f.write(chunk) + except requests.exceptions.RequestException as e: + print(f"Couldn't download the app: {e}") + sys.exit(1) + +if __name__ == "__main__": + main() + +``` + +

+
+ + + + + +:::tip +If you are a self-hosted Appcircle server user, you can change the required URL variables for your own needs and use the same method. +::: + +:::caution +Please create the PAT from the root organization. If you do not create it from the sub-organization, you will not be able to download the app versions available in the Enterprise App Store profiles of either the root organization or the organization where you created the PAT. +::: \ No newline at end of file From b69f81d2262366ebfed690ae5df252ddfe4c7ee7 Mon Sep 17 00:00:00 2001 From: burakberkkeskin Date: Mon, 26 Aug 2024 14:42:54 +0300 Subject: [PATCH 2/9] grammar fix --- docs/appcircle-api/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/appcircle-api/faq.md b/docs/appcircle-api/faq.md index 54011ec3d..50e331275 100644 --- a/docs/appcircle-api/faq.md +++ b/docs/appcircle-api/faq.md @@ -16,7 +16,7 @@ This section is designed to help you quickly find answers to common questions an ### How can I check the versions of an app published in the Enterprise App Store and download it? -After you have successfully [created the Personal API Token](/appcircle-api/api-authentication.md#generatingmanaging-the-personal-api-tokens) from the **root organization**, you can check the versions of an application and download them like in the following example code blocks. +After you have successfully [created the Personal API Token](/appcircle-api/api-authentication.md#generatingmanaging-the-personal-api-tokens) from the **root organization**, you can check the versions of an application and download them, like in the following example code blocks. :::caution You must create the PAT on the root organization. Requests will fail if you create the PAT from a sub-organization. From 93ab60b345fdbd4f02ecf225d6c9e4f09642d785 Mon Sep 17 00:00:00 2001 From: burakberkkeskin Date: Mon, 26 Aug 2024 17:45:08 +0300 Subject: [PATCH 3/9] added a caution line and changed URLs --- docs/appcircle-api/faq.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/appcircle-api/faq.md b/docs/appcircle-api/faq.md index 50e331275..38819dc4c 100644 --- a/docs/appcircle-api/faq.md +++ b/docs/appcircle-api/faq.md @@ -42,9 +42,10 @@ values={[ set -uo pipefail PERSONAL_ACCESS_TOKEN="SuperSecretPatTakenFromRootOrganization==" +# Please be cautious, URLs shouldn't end with '/'. API_URL="https://api.appcircle.io" # API URL for Appcircle cloud AUTH_URL="https://auth.appcircle.io" # AUTH URL for Appcircle cloud -STORE_URL="https://mystore.self.appcircle.io" # Your default or custom store URL on Appcircle cloud. +STORE_URL="https://mycustomstoredomain.appcircle.io" # Your default or custom store URL on Appcircle cloud. echo -e "Authenticating to the $AUTH_URL \n" TOKEN_JSON_RESPONSE=$(curl -fs -X POST "${AUTH_URL}/auth/v1/token" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "pat=$PERSONAL_ACCESS_TOKEN") @@ -119,9 +120,10 @@ import sys import json PERSONAL_ACCESS_TOKEN = "SuperSecretPatTakenFromRootOrganization==" +# Please be cautious, URLs shouldn't end with '/'. API_URL = "https://api.self.appcircle.io" # API URL for Appcircle cloud AUTH_URL = "https://auth.self.appcircle.io" # AUTH URL for Appcircle cloud -STORE_URL = "https://mystore.self.appcircle.io" # Your default or custom store URL on Appcircle cloud. +STORE_URL = "https://mycustomstoredomain.appcircle.io" # Your default or custom store URL on Appcircle cloud. def main(): print(f"Authenticating to {AUTH_URL}\n") From 097a4129c43918bb39d83aeff4deddd239bb882c Mon Sep 17 00:00:00 2001 From: Burak Berk Date: Mon, 2 Sep 2024 20:14:47 +0300 Subject: [PATCH 4/9] updated self-hosted URLs to prod cloud URLs --- docs/appcircle-api/faq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/appcircle-api/faq.md b/docs/appcircle-api/faq.md index 38819dc4c..045de8ad7 100644 --- a/docs/appcircle-api/faq.md +++ b/docs/appcircle-api/faq.md @@ -121,8 +121,8 @@ import json PERSONAL_ACCESS_TOKEN = "SuperSecretPatTakenFromRootOrganization==" # Please be cautious, URLs shouldn't end with '/'. -API_URL = "https://api.self.appcircle.io" # API URL for Appcircle cloud -AUTH_URL = "https://auth.self.appcircle.io" # AUTH URL for Appcircle cloud +API_URL = "https://api.appcircle.io" # API URL for Appcircle cloud +AUTH_URL = "https://auth.appcircle.io" # AUTH URL for Appcircle cloud STORE_URL = "https://mycustomstoredomain.appcircle.io" # Your default or custom store URL on Appcircle cloud. def main(): @@ -221,4 +221,4 @@ If you are a self-hosted Appcircle server user, you can change the required URL :::caution Please create the PAT from the root organization. If you do not create it from the sub-organization, you will not be able to download the app versions available in the Enterprise App Store profiles of either the root organization or the organization where you created the PAT. -::: \ No newline at end of file +::: From 83978257a93523b2ae2dcbdc6504b67994c9762c Mon Sep 17 00:00:00 2001 From: burakberkkeskin Date: Wed, 4 Sep 2024 13:35:46 +0300 Subject: [PATCH 5/9] changed access token to api token --- docs/appcircle-api/faq.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/appcircle-api/faq.md b/docs/appcircle-api/faq.md index 045de8ad7..830e026f5 100644 --- a/docs/appcircle-api/faq.md +++ b/docs/appcircle-api/faq.md @@ -41,14 +41,14 @@ values={[ set -uo pipefail -PERSONAL_ACCESS_TOKEN="SuperSecretPatTakenFromRootOrganization==" +PERSONAL_API_TOKEN="SuperSecretPatTakenFromRootOrganization==" # Please be cautious, URLs shouldn't end with '/'. API_URL="https://api.appcircle.io" # API URL for Appcircle cloud AUTH_URL="https://auth.appcircle.io" # AUTH URL for Appcircle cloud STORE_URL="https://mycustomstoredomain.appcircle.io" # Your default or custom store URL on Appcircle cloud. echo -e "Authenticating to the $AUTH_URL \n" -TOKEN_JSON_RESPONSE=$(curl -fs -X POST "${AUTH_URL}/auth/v1/token" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "pat=$PERSONAL_ACCESS_TOKEN") +TOKEN_JSON_RESPONSE=$(curl -fs -X POST "${AUTH_URL}/auth/v1/token" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "pat=$PERSONAL_API_TOKEN") if [[ "$?" != "0" ]]; then echo "Couldn't authenticate to the $API_URL with the PAT." echo "Please check your PAT." @@ -119,7 +119,7 @@ import requests import sys import json -PERSONAL_ACCESS_TOKEN = "SuperSecretPatTakenFromRootOrganization==" +PERSONAL_API_TOKEN = "SuperSecretPatTakenFromRootOrganization==" # Please be cautious, URLs shouldn't end with '/'. API_URL = "https://api.appcircle.io" # API URL for Appcircle cloud AUTH_URL = "https://auth.appcircle.io" # AUTH URL for Appcircle cloud @@ -131,7 +131,7 @@ def main(): token_response = requests.post( f"{AUTH_URL}/auth/v1/token", headers={"accept": "application/json", "Content-Type": "application/x-www-form-urlencoded"}, - data={"pat": PERSONAL_ACCESS_TOKEN} + data={"pat": PERSONAL_API_TOKEN} ) token_response.raise_for_status() except requests.exceptions.RequestException as e: From 2e83701652aad4cd15224c10a8ca582beadf6dc1 Mon Sep 17 00:00:00 2001 From: burakberkkeskin Date: Wed, 4 Sep 2024 13:37:19 +0300 Subject: [PATCH 6/9] add description for pat --- docs/appcircle-api/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/appcircle-api/faq.md b/docs/appcircle-api/faq.md index 830e026f5..8c555578d 100644 --- a/docs/appcircle-api/faq.md +++ b/docs/appcircle-api/faq.md @@ -19,7 +19,7 @@ This section is designed to help you quickly find answers to common questions an After you have successfully [created the Personal API Token](/appcircle-api/api-authentication.md#generatingmanaging-the-personal-api-tokens) from the **root organization**, you can check the versions of an application and download them, like in the following example code blocks. :::caution -You must create the PAT on the root organization. Requests will fail if you create the PAT from a sub-organization. +You must create the PAT (Personal API Token) on the root organization. Requests will fail if you create the PAT from a sub-organization. ::: Date: Wed, 4 Sep 2024 13:45:35 +0300 Subject: [PATCH 7/9] added meanings of the variables --- docs/appcircle-api/faq.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/appcircle-api/faq.md b/docs/appcircle-api/faq.md index 8c555578d..3242c00dc 100644 --- a/docs/appcircle-api/faq.md +++ b/docs/appcircle-api/faq.md @@ -22,6 +22,18 @@ After you have successfully [created the Personal API Token](/appcircle-api/api- You must create the PAT (Personal API Token) on the root organization. Requests will fail if you create the PAT from a sub-organization. ::: +You should change the required variables for your own needs before using the same code samples. + +If you are a cloud Appcircle server user, you should change the variables below: + +- `PERSONAL_API_TOKEN`: The PAT that created from the root organization. +- `STORE_URL`: The default or custom store URL you use to access to your Appcircle Enterprise App Store. + +If you are using the self-hosted Appcircle server, you should change the following variables in addition to the ones above: + +- `API_URL`: The API URL for your self-hosted Appcircle server. If you are accessing Appcircle dashboard with a URL like “https://my.appcircle.spacetech.com”, your `API` URL will usually be “https://api.appcircle.spacetech.com”. +- `AUTH_URL`: The Authentication URL for your self-hosted Appcircle server. If you are accessing Appcircle dashboard with a URL like “https://my.appcircle.spacetech.com”, your `AUTH` URL will usually be “https://auth.appcircle.spacetech.com”. + Date: Wed, 4 Sep 2024 13:57:18 +0300 Subject: [PATCH 8/9] changed url types --- docs/appcircle-api/faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/appcircle-api/faq.md b/docs/appcircle-api/faq.md index 3242c00dc..ee726647f 100644 --- a/docs/appcircle-api/faq.md +++ b/docs/appcircle-api/faq.md @@ -31,8 +31,8 @@ If you are a cloud Appcircle server user, you should change the variables below: If you are using the self-hosted Appcircle server, you should change the following variables in addition to the ones above: -- `API_URL`: The API URL for your self-hosted Appcircle server. If you are accessing Appcircle dashboard with a URL like “https://my.appcircle.spacetech.com”, your `API` URL will usually be “https://api.appcircle.spacetech.com”. -- `AUTH_URL`: The Authentication URL for your self-hosted Appcircle server. If you are accessing Appcircle dashboard with a URL like “https://my.appcircle.spacetech.com”, your `AUTH` URL will usually be “https://auth.appcircle.spacetech.com”. +- `API_URL`: The API URL for your self-hosted Appcircle server. If you are accessing Appcircle dashboard with a URL like `https://my.appcircle.spacetech.com`, your `API` URL will usually be`https://api.appcircle.spacetech.com`. +- `AUTH_URL`: The Authentication URL for your self-hosted Appcircle server. If you are accessing Appcircle dashboard with a URL like `https://my.appcircle.spacetech.com`, your `AUTH` URL will usually be `https://auth.appcircle.spacetech.com`. Date: Wed, 4 Sep 2024 14:44:53 +0300 Subject: [PATCH 9/9] minor typo --- docs/appcircle-api/faq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/appcircle-api/faq.md b/docs/appcircle-api/faq.md index ee726647f..f475764aa 100644 --- a/docs/appcircle-api/faq.md +++ b/docs/appcircle-api/faq.md @@ -26,12 +26,12 @@ You should change the required variables for your own needs before using the sam If you are a cloud Appcircle server user, you should change the variables below: -- `PERSONAL_API_TOKEN`: The PAT that created from the root organization. -- `STORE_URL`: The default or custom store URL you use to access to your Appcircle Enterprise App Store. +- `PERSONAL_API_TOKEN`: The PAT created from the root organization. +- `STORE_URL`: The default or custom store URL you use to access your Appcircle Enterprise App Store. If you are using the self-hosted Appcircle server, you should change the following variables in addition to the ones above: -- `API_URL`: The API URL for your self-hosted Appcircle server. If you are accessing Appcircle dashboard with a URL like `https://my.appcircle.spacetech.com`, your `API` URL will usually be`https://api.appcircle.spacetech.com`. +- `API_URL`: The API URL for your self-hosted Appcircle server. If you are accessing Appcircle dashboard with a URL like `https://my.appcircle.spacetech.com`, your `API` URL will usually be `https://api.appcircle.spacetech.com`. - `AUTH_URL`: The Authentication URL for your self-hosted Appcircle server. If you are accessing Appcircle dashboard with a URL like `https://my.appcircle.spacetech.com`, your `AUTH` URL will usually be `https://auth.appcircle.spacetech.com`.