Upload an app using the Kobiton API (Terminal)

Learn how to upload an app to the app repository using our REST API.

Before you start

Throughtout this document, replace https://api.kobiton.com with [http/https]://[Dell server IP or hostname]:3000 if you are using Standalone server.

Configure your authorization header

To ensure your credentials are kept secure, all requests sent to https://api.kobiton.com/ must contain an Authentication header. Credentials assigned to your authorization header need to be in base64 format.

In your terminal, convert your Kobiton API credentials to base64 format using the following command:

echo -n "${yourUserNameOrEmail}:${yourApiKey}" | base64

Copy the generated string and save it in a secure location for later.

Generate an upload URL

In a terminal, make a POST request to /v2/apps/uploadUrl to generate a unique upload URL that connects to our private S3 bucket on Amazon Web Services (AWS). Use the following cURL command:

curl -X POST https://api.kobiton.com/v2/apps/upload-url \
  -H 'Authorization: Basic ${yourBase64String}' \
  -H 'Content-Type: application/json' \
  -d '{ "file_name": "${app_file_name}" , "app_id": ${app_id} }'

The request has 2 parameters:

  • ${app_id}: (optional) Provide the app_id if another version of this app is already uploaded. Example: 100.

  • ${app_file_name}: (required) Name of the app file to upload. Example: MyApp.ipa.

You can look up the app_id in app metadata.

We will use the app MyApp.ipa throughout this guide to demonstrate the upload process. Assuming this app does not exist in the repository, there is no need to specify an app_id:

curl -X POST https://api.kobiton.com/v2/apps/upload-url \
  -H 'Authorization: Basic ${yourBase64String}' \
  -H 'Content-Type: application/json' \
  -d '{ "file_name": "MyApp.ipa" }'

A successful response will return the following:

Example
{
    "app_path": "users/1/apps/MyApp‐237824a0‐302c‐9bfd‐ff417c89610a.ipa",
    "url": "https://kobiton-us-west.s3.amazonaws.com/users/78042/apps/MyApp-57b15160-cf17-11ee-98d5-e949a34321c7f.ipa?AWSAccessKeyId=AKIAYOIAYUIRGDSFS6QO&Content-Type=application%2Foctet-stream&Expires=1708384165&Signature=VHTRqXdIpKmbvauPsdfsKJhAgk%3D&x-amz-acl=private&x-amz-meta-appid=600841&x-amz-meta-createdby=78042&x-amz-meta-organizationid=681&x-amz-tagging=unsaved%3Dtrue"
}

Save the above values for the next sections.

Upload app file to S3 storage

Make a PUT request to the previously generated url to upload the app file to S3 storage.

curl -X PUT ${url} \
  -H "Content-Type: application/octet-stream" \
  -H "x-amz-tagging: unsaved=true" \
  -T ${file_path}

This request requires:

  • ${url}: The url obtained from the previous section.

  • ${file_path}: Path to the app package file you want to upload.

Example command using the previous section’s response:

curl -X PUT https://kobiton-us-west.s3.amazonaws.com/users/78042/apps/MyApp-57b15160-cf17-11ee-98d5-e949a34321c7f.ipa?AWSAccessKeyId=AKIAYOIAYUIRGDSFS6QO&Content-Type=application%2Foctet-stream&Expires=1708384165&Signature=VHTRqXdIpKmbvauPsdfsKJhAgk%3D&x-amz-acl=private&x-amz-meta-appid=600841&x-amz-meta-createdby=78042&x-amz-meta-organizationid=681&x-amz-tagging=unsaved%3Dtrue  \
  -H "Content-Type: application/octet-stream" \
  -H "x-amz-tagging: unsaved=true" \
  -T /the/full/file/path/on/my/local/computer/MyApp.ipa

A blank response indicates a successful upload.

Create the app or app version in the app repository

Make a POST request to create the entry for the app or app version in the app repository on Kobiton.

curl -X POST https://api.kobiton.com/v2/apps \
    -H 'Authorization: Basic ${yourBase64String}' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{ "file_name": "${app_file_name}" , "app_path": "${app_path}" }'

This request contains 2 parameters:

  • ${app_path}: (required) Use the value of app_path from the previous step.

  • ${app_file_name}: (optional) Specify the name of the app. If not provided, the name of the file from ${app_path} is used.

Continuing on from the previous steps, your command would be:

curl -X POST https://api.kobiton.com/v2/apps \
    -H 'Authorization: Basic ${yourBase64String}' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{ "MyApp.ipa": "" , "app_path": "users/1/apps/MyApp‐237824a0‐302c‐9bfd‐ff417c89610a.ipa" }'

If your request was successful, POST will return a 200 status with the following response:

{
  "app_id": 100,
  "version_id": 101
}

In the response above, app_id is the ID of the new app, and version_id is the ID of the new application version.

If the app file is too large, it may take a while to process the file and the value of app_id will be N/A. See the next section on how to obtain the app_id.

Obtain the app ID

Make a GET request to obtain the parsing status and the app_id of your newly uploaded app.

curl -X GET 'https://api.kobiton.com/v2/apps/parsing-status?appVersionId=${version_id}' \
    -H 'Authorization: Basic ${yourBase64String}'

This request requires the version_id obtained from the previous step.

Continuing on with the example, your command would be:

curl -X GET 'https://api.kobiton.com/v2/apps/parsing-status?appVersionId=101' \
    -H 'Authorization: Basic ${yourBase64String}'

If your request was successful, GET will return a 200 status with the following response:

{
"app_id": 100,
"state": "OK"
}

The response has 2 parameters:

  • state: indicates the parsing status of the app.

    • OK: The uploaded application is processed by the server and is ready to use.

    • PARSING: The server is still processing the uploaded application.

    • FAILURE_PARSING: The server could not process the uploaded application, typically due to an invalid file type.

  • app_id: the ID of the app to use in other endpoints such as installing the app on a device or get information about a specific app.

If you receive error 404 with the message App version ID …​ doesn’t exist, the application version might be made inaccessible to your account. Contact an admin for access.