Skip to content

The Bitbar API service provides plenty of requests that help to not only query the test results but also configure test settings and directly launch test runs in Bitbar Device Cloud from your environment. With the cloud domain change two months ago, it’s good time to recap what API calls are needed and how to get the most out of the Bitbar API service to improve DevOps pipeline efficiency and developer productivity.

More specifically, the reasons to use the API service are simple.

  • You already have an optimal CI/CD pipeline but want to expand test coverage with additional devices.
  • Your current testing capacity is not sufficient and you want to use additional devices from the cloud.
  • Or you are just frustrated to traverse multiple UIs to relaunch your tests against new app versions.

The below steps describe how to get information about existing settings and projects from Bitbar Cloud and how to launch test runs in the cloud with changing apps or tests.

In all of the examples below, you’ll need to replace `${CLOUD_URL}` with your cloud URL ${API_KEY}. For public cloud users that would be ‘‘ while Bitbar Enterprise customers with Private Cloud or On-Premise setup will have different addresses. Most of the used resources are behind authentication, for which we use the API key variable ${API_KEY}. Set this to your own.

Also we’ll use curl to demonstrate the calls, but of course you can use any other scripting/programmatic approach that better suits your needs.

Gathering Project and Run Information

If you already have some projects, then it’s a natural first step to check the configurations of these projects. You’ll need this information when you want to start new runs on existing projects.

Getting project information

To query all of your projects, you need to use the ‘/api/v2/me/projects‘ endpoint. This will return all of your projects and specifically the project IDs that is needed to programmatically interact with the project. This also applies to when you create new test runs.

curl -X GET "${CLOUD_URL}/api/v2/me/projects" -u "${API_KEY}": | jq '.'

To get a specific project with a name, you can now use the API filtering options to filter all of the projects but only the one you are interested in.

curl -X GET "${CLOUD_URL}/api/v2/me/projects?filter=s_name_eq_DetoxAndroid" -u "${API_KEY}": | jq '.'
  "data": [
      "id": 148036994,
      "archivingItemCount": 120,
      "archivingStrategy": "DAYS",
      "common": false,
      "description": "",
      "name": "DetoxAndroid",
      "sharedByEmail": "",
      "sharedById": 756577998,
      "createTime": 152430770000,
      "archiveTime": null,
      "frameworkId": 541,
      "successRatio": null,
      "osType": "ANDROID",
      "shared": false,
      "archivingStrategyDisplayValue": "120 days"
"limit": 20,
"next": null,
"offset": 0,
"previous": null,
"search": "",
"sort": "",
"total": 1,
"empty": false
Getting runs information

To automate the launching of the last run, you can just get the latest run from a project and then restart it. If you don’t know the project ID, you’ll need to find it using the above calls and filtering options.

# getting the ID for a named project
curl -X GET "${CLOUD_URL}/api/v2/me/runs?filter=n_projectId_eq_138438436" -u "${API_KEY}": | jq '.data[0].id'
# finding last run for previous project - sort projects runs in descending order
curl -X GET "${CLOUD_URL}/api/v2/me/projects/143374637/runs?sort=createTime_d" -u "${API_KEY}": | jq '.data[0].id'

Upload new test and app files and then start a new test run in an existing project. To create a new test run in that project with a new app, eg. a new build version.

# upload a new app to the project and store the response app ID
curl -X POST -F 'file=@path/to/local/app' "${CLOUD_URL}/api/v2/me/projects/143374637/files/application" -u "${API_KEY}": | jq ‘. | if .id then .id else .message end’
# to upload a test file, use /api/v2/me/projects/<project id>/files/test

Getting available frameworks

In the previous example we have been working on existing projects. To create a new project you’ll need to know the testing framework that your tests are going to use. There are multiple frameworks available and not all are available to all users. Query to check which you can use:

# get all available frameworks
curl -X GET "${CLOUD_URL}/api/v2/me/available-frameworks" -u "${API_KEY}": | jq '.'

The response message will have the framework names (e.g. Appium Android Server Side), the required files and types etc. You’ll mostly need the framework name while creating a new project or the ID when launching a new test run for an existing project.

Creating a new project

If you are starting from scratch, you’ll need to create a new project before you can start test runs. Creating a project is also a simple API call away, but you need to know some parameters for the project to behave as you expect. These are the project name and framework type (available types queried earlier). Here’s an example of such a call.

# create a new project, adding name, framework and OS type information
curl -X POST "${CLOUD_URL}/api/v2/me/projects" -u "${API_KEY}": --data "name=curl-created" --data "type=APPIUM_ANDROID_SERVER_SIDE" | jq '.'
# response to above POST
  "id": 42150585,
  "archivingItemCount": 120,
  "archivingStrategy": "DAYS",
  "common": false,
  "description": "",
  "name": "curl-created",
  "sharedByEmail": "",
  "sharedById": 32843110,
  "createTime": 1529562949000,
  "archiveTime": null,
  "frameworkId": 559,
  "successRatio": null,
  "osType": "ANDROID",
  "shared": false,
  "archivingStrategyDisplayValue": "120 days"

Launching Runs

Once you have uploaded files and stored the response IDs, you can start a new test run with all the configurations for the project you want. This is the best approach to make sure which configuration gets used with your run.

curl -s "${CLOUD_URL}"'api/v2/me/runs' -H "Content-Type: application/json" -u "${API_KEY}": -X POST --data '{"osType":"'"${OS_TYPE}"'","projectId":"'"${PROJECT_ID}"'","frameworkId":"'"${FRAMEWORKID}"'","files":[{"id":"'"${APP_FILE_ID}"'", "action":"INSTALL"},{"id":"'"${TEST_FILE_ID}"'", "action":"RUN_TEST"}],"deviceGroupId":"'"${DEVICE_GROUP_ID}"'"}' | jq '. | if .id then .id else .message end'

The run configuration of the test run should be provided as part of the run command like above with ‘--data‘ parameter.

In earlier API versions, it was possible to start a test run in two phases. In some heavily automated environments, this could cause a case where a second configuration was uploaded before the first run had yet started. This of course caused confusion when reviewing results!

Getting Familiar With Bitbar API

Private Cloud users and all registered users (after release 2.61, planned for 28.6.) can access the API documentation at $CLOUD_URL/cloud/swagger-ui.html. This Swagger service allows you to read through the API documentation and even try running commands from the web interface. This way you can try out your calls before writing your scripts for CI automation!

Niko Cankar

Bitbar Product Owner