HTTP API Reference¶

For the examples, we’ll use httpie (can be installed with pip). We’ll omit CONTENT-LENGTH, DATE and SERVER response headers.

$ mkdir ~/.httpie; echo '{"default_options":["--session=default"]}' > ~/.httpie/config.json
$ pip install httpie
Collecting httpie
[...]
Successfully installed httpie-0.9.9

When directly connected to the kyaraben server beyond the authentication component (we’ll assume port localhost:8084) the current user can be specified with the X-Auth-UserId header:

404 errors are possible in most cases, and will happen - for security reasons - even when the user does not exist, or the user exists but does not have permission to access the resource.

$ http :8084/user/whoami
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
    "error": "Missing authentication header"
}

$ http :8084/user/whoami X-Auth-UserId:marco
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "user": {
        "userid": "marco"
    }
}

Since we defined a default session for httpie, the user header is persistent, there is no need to repeat it.

$ http :8084/user/whoami
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "user": {
        "userid": "marco"
    }
}

GET /android¶

Return the Android VMs that belong to a user

Example request:

$ http :8084/android

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "avms": [
        {
            "avm_id": "f40d2ec4b55911e6a436fa163e316d19",
            "avm_name": "f40d2ec4",
            "avm_owner": "marco",
            "campaign_id": "",
            "image": "kitkat-tablet",
            "project_id": "fb651ee0b31d11e6a436fa163e316d19",
            "status": "READY",
            "ts_created": "2016-11-28T11:01:03Z",
            "uptime": 22226.51023
        },
        {
            "avm_id": "ededb9ccb58c11e6a436fa163e316d19",
            "avm_name": "ededb9cc",
            "avm_owner": "marco",
            "campaign_id": "",
            "image": "lollipop-phone",
            "project_id": "fb651ee0b31d11e6a436fa163e316d19",
            "status": "READY",
            "ts_created": "2016-11-28T17:05:57Z",
            "uptime": 334.477165
        }
    ]
}

Request Headers:
	X-Auth-UserId – the user who created and owns the virtual machines. If the user does not exist, no error is reported and an empty list is returned
Status Codes:	200 OK – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	avm_id (uuid) – unique identifier avm_name (string) – user-provided name, or generated from avm_id if not provided avm_owner (string) – the user who owns the AVM campaign_id (uuid) – for async vms, id of the test campaign image (string) – Android image used to instantiate the AVM project_id (uuid) – parent project of the AVM status (string) – one of (QUEUED, CREATING, READY, DELETING, DELETED, ERROR) ts_created (iso8601) – timestamp of the creation uptime (float) – longevity of the VM, in seconds

GET /android/(string: avm_id)¶

Status and metadata of an Android Virtual Machine.

Example request:

$ http :8084/android/30adc730b63111e6a436fa163e316d19

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "avm": {
        "avm_id": "30adc730b63111e6a436fa163e316d19",
        "avm_name": "first vm",
        "avm_owner": "marco",
        "campaign_id": "",
        "hwconfig": {
            "dpi": 160,
            "enable_battery": 0,
            "enable_camera": 1,
            "enable_gps": 1,
            "enable_gsm": 1,
            "enable_nfc": 0,
            "enable_record": 0,
            "enable_sensors": 1,
            "height": 800,
            "width": 1280
        },
        "image": "kitkat-tablet",
        "project_id": "e1df30bcb61c11e6a436fa163e316d19",
        "status": "READY",
        "status_reason": "",
        "status_ts": "2016-11-29T12:42:56Z",
        "ts_created": "2016-11-29T12:41:46Z",
        "uptime": 1648.454066
    }
}

Request Headers:
	X-Auth-UserId – the user who created and owns the virtual machine
Parameters:	avm_id – the virtual machine identifier
Status Codes:	200 OK – no error 404 Not Found – there is no vm identified by avm_id, or it exists but does not belong to the user, or the user itself does not exist
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	avm_id (uuid) – virtual machine identifier avm_name (string) – given or generated VM name avm_owner (string) – the user who owns the AVM campaign_id (uuid) – the id of the test campaign (for async vms) hwconfig (object) – the environment configuration provided at time of creation image (string) – Android image used to create the VM project_id (uuid) – parent project of the AVM status (string) – one of (QUEUED, CREATING, DELETING, READY, DELETED, ERROR) status_reason (string) – status details (when status=ERROR) status_ts (iso8601) – timestamp of the status ts_created (iso8601) – timestamp of the creation uptime (float) – longevity of the VM, in seconds

GET /android/(string: avm_id)/apk¶

List of the third party, enabled packages installed in a VM. System or disabled applications are not returned.

Example request:

$ http :8084/android/78292832b70011e69093fa163e5f2779/apk

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "packages": [
        "com.example.android.apis",
        "com.android.gesture.builder"
    ]
}

Request Headers:
	X-Auth-UserId – a user who has access to the virtual machine
Parameters:	avm_id – the virtual machine identifier
Status Codes:	200 OK – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	packages (array) – list of package names

GET /android/(string: avm_id)/command/(string: command_id)¶

Retrieve output of a remote command run on a VM.

This is used to capture logs of test runs, monkey tool and apk installation.

Example request:

$ http :8084/android/78292832b70011e69093fa163e5f2779/command/30c88f2cb71011e69093fa163e5f2779

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "results": [
        {
            "returncode": "0",
            "status": "READY",
            "stderr": "3880 KB/s (872273 bytes in 0.219s)",
            "stdout": "pkg: /data/local/tmp/282831ecb71011e69093fa163e5f2779.apk\nSuccess"
        }
    ]
}

Request Headers:
	X-Auth-UserId – a user who has access to the AVM
Parameters:	avm_id – the virtual machine identifier command_id – a command identifier
Status Codes:	200 OK – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	returncode (string) – the return code of the adb command status (string) – one of (QUEUED, RUNNING, READY, ERROR) stderr (string) – the captured standard error stdout (string) – the captured standard output

GET /android/(string: avm_id)/properties¶

Retrieve the current values of Android properties.

Example request:

$ http :8084/android/78292832b70011e69093fa163e5f2779/properties

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "properties": {
        "aicVM.gles": "1",
        "aicVM.gles.renderer": "1",
        "aicVM.inited": "1",
        "aicd.ac.online": "1",
        "aicd.accelerometer.x": "0.000000",
        "aicd.accelerometer.y": "9.776219",
        "aicd.accelerometer.z": "0.813417",
        "...": "...",
        "sys.settings_system_version": "12",
        "sys.sysctl.extra_free_kbytes": "5625",
        "sys.sysctl.tcp_def_init_rwnd": "60",
        "sys.usb.config": "adb",
        "sys.usb.state": "adb",
        "wifi.interface": "eth1",
        "wifi.interface.mac": "fa:16:3e:6e:9d:aa",
        "wlan.driver.status": "ok"
    }
}

Request Headers:
	X-Auth-UserId – a user who has access to the AVM
Parameters:	avm_id – the virtual machine identifier
Status Codes:	200 OK – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	properties (object) – an object of {property_name: property_value, ...}

GET /android/(string: avm_id)/testrun¶

List the test packages installed in a VM.

Note

This API is misplaced. It’s more the test equivalent of GET /android/{android_id}/apk than the counterpart to PUT /android/{android_id}/testrun.

Example request:

$ http :8084/android/78292832b70011e69093fa163e5f2779/testrun

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "packages": {
        "com.example.android.apis/.app.LocalSampleInstrumentation": "com.example.android.apis",
        "com.zenika.aic.core.libs.test/android.test.InstrumentationTestRunner": "com.zenika.aic.core.libs.test"
    }
}

Request Headers:
	X-Auth-UserId – a user who has access to the AVM
Parameters:	avm_id – the virtual machine identifier
Status Codes:	200 OK – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	packages (object) – an object of the form {package_name: target, ...}

GET /android/(string: avm_id)/totp¶

Generate a Time-Based One-Time Password to connect to the Android display. The password is valid for 30 seconds.

Example request:

$ http :8084/android/78292832b70011e69093fa163e5f2779/totp

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "totp": "226688"
}

Request Headers:
	X-Auth-UserId – a user who has access to the AVM
Parameters:	avm_id – the virtual machine identifier
Status Codes:	200 OK – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	totp (string) – a password to be sent to the remote VNC server, or the reverse proxy

POST /android¶

Create an Android VM and assign it to the current user.

A positive response means the creation of the AVM has been started. As soon as the resources have been created and the services deployed, the VM status becomes READY, even though the VM is still booting up.

Errors coming from OpenStack (for instance, if the creation would cause the user to go over the quota allocated to the tenant, or a networking issue) will leave the AVM resource with a status of ERROR and the creation tasks automatically rescheduled, to be retried when the (hopefully transient) problem is fixed. More details about such errors (and exception traceback) can be found either in worker logs, or in the SQL database (column avms.status_reason).

The only required values are project_id and image.

Example request:

$ http post :8084/android \
project_id=e1df30bcb61c11e6a436fa163e316d19 \
image=kitkat-tablet \
hwconfig:='{"width":1280,"height":800,"enable_battery":0}' \
avm_name=first_avm

Example response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "avm_id": "e005e700b62f11e6a436fa163e316d19"
}

Request Headers:
	X-Auth-UserId – a user who will own the AVM
Request JSON Object:
	project_id (uuid) – parent project of the AVM image (string) – Android image to use avm_name (string) – optional VM name. If missing, part of the id will be used hwconfig (object) – object with one or more of the following keys hwconfig["width"] (integer) – screen width hwconfig["height"] (integer) – screen height hwconfig["dpi"] (integer) – screen DPI hwconfig["enable_sensors"] (integer) – 0/1 hwconfig["enable_battery"] (integer) – 0/1 hwconfig["enable_gps"] (integer) – 0/1 hwconfig["enable_camera"] (integer) – 0/1 hwconfig["enable_record"] (integer) – 0/1 hwconfig["enable_gsm"] (integer) – 0/1 hwconfig["enable_nfc"] (integer) – 0/1
Status Codes:	201 Created – the creation of AVM and services has started 400 Bad Request – malformed request (response contains the expected JSON schema)
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	avm_id (uuid) – unique identifier

POST /android/(string: avm_id)/apk/(string: apk_id)¶

Install an application in a running VM. The APK file must have been previously uploaded to the project. The request returns the ID of an asynchronous command. The application can be reinstalled multiple times without uninstalling.

Example request:

$ http post :8084/android/78292832b70011e69093fa163e5f2779/apk/282831ecb71011e69093fa163e5f2779

Example response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8

{
    "command_id": "e9c40926b71911e69093fa163e5f2779"
}

Request Headers:
	X-Auth-UserId – a user who has access to the AVM
Parameters:	avm_id – the virtual machine identifier apk_id – the APK identifier
Status Codes:	202 Accepted – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	command_id (uuid) – a command identifier

POST /android/(string: avm_id)/monkey¶

Execute the UI/Application Exerciser Monkey on an application.

Example request:

$ http post :8084/android/78292832b70011e69093fa163e5f2779/monkey \
packages:='["com.uberspot.a2048","com.example.android.apis"]' \
event_count=100

Example response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8

{
    "command_id": "e0f7a8eab71711e69093fa163e5f2779"
}

Request Headers:
	X-Auth-UserId – a user who has access to the AVM
Parameters:	avm_id – the virtual machine identifier
Status Codes:	202 Accepted – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	command_id (uuid) – a command identifier

POST /android/(string: avm_id)/testrun¶

Run instrumented test packages.

Example request:

$ http post :8084/android/78292832b70011e69093fa163e5f2779/testrun package=com.uberspot.a2048

Example response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8

{
    "command_id": "8d9f07a6b72111e69093fa163e5f2779"
}

Request Headers:
	X-Auth-UserId – a user who has access to the AVM
Parameters:	avm_id – uuid of the VM
Request JSON Object:
	package (string) – name of the test package to run
Status Codes:	202 Accepted – no error
Response JSON Object:
	command_id (uuid) – a command identifier

PUT /android¶

Changes metadata of an Android VM (currently only the name).

Example request:

$ http put :8084/android/78292832b70011e69093fa163e5f2779 avm_name=totoro

Example response:

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: application/octet-stream

Request Headers:
	X-Auth-UserId – a user who has access to the AVM
Parameters:	avm_id – uuid of the VM
Request JSON Object:
	avm_name (string) – new VM name
Status Codes:	204 No Content – the name of the VM has been changed

DELETE /android/(string: avm_id)¶

Remove an AVM and its associated services (video rendering, web console, adb).

Like its creation counterpart, this operation is asynchronous and returns a positive response as soon as the removal has started. Failures to delete Heat stacks are not handled by this API.

Example request:

$ http delete :8084/android/30adc730b63111e6a436fa163e316d19

Example response:

HTTP/1.1 202 Accepted

Request Headers:
	X-Auth-UserId – a user who has access to the AVM
Parameters:	avm_id – the identifier of the AVM to remove
Status Codes:	202 Accepted – the removal of AVM and services has started 404 Not Found – the AVM does not exist, or does not belong to the user, or the user does not exist

GET /images¶

Returns the list of the available Android images.

Example request:

$ http :8084/images

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "images": [
        {
            "android_version": 4,
            "image": "kitkat-tablet"
        },
        {
            "android_version": 4,
            "image": "kitkat-phone"
        },
        {
            "android_version": 5,
            "image": "lollipop-tablet"
        },
        {
            "android_version": 5,
            "image": "lollipop-phone"
        }
    ]
}

Request Headers:
	X-Auth-UserId – a user who has access to the AVM
Parameters:	avm_id – the virtual machine identifier
Status Codes:	200 OK – no error
Response JSON Object:
	image (string) – the prefix to be used when retrieving system and data images in OpenStack Glance android_version (int) – the major version of Android, used to link the right OpenGL libraries in the player containers

GET /projects¶

Returns the projects the user has access to.

Example request:

$ http :8084/projects

Example response:

HTTP/1.1 200 OK

{
    "projects": [
        {
            "project_id": "5416126cb64b11e69093fa163e5f2779",
            "project_name": "foo",
            "status": "READY"
        }
    ]
}

Request Headers:
	X-Auth-UserId – the user who created, or with whom the projects are shared. If the user does not exist, no error is reported and an empty list is returned
Status Codes:	200 OK – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	project_id (uuid) – unique identifier project_name (string) – user-provided name status (string) – one of (QUEUED, CREATING, READY, DELETING, DELETED, ERROR)

GET /projects/(string: project_id)¶

Status and metadata of a project.

Example request:

$ http :8084/projects/5416126cb64b11e69093fa163e5f2779

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "project": {
        "count_avms": 0,
        "project_id": "5416126cb64b11e69093fa163e5f2779",
        "project_name": "foo",
        "status": "READY",
        "status_reason": "",
        "status_ts": "2016-11-29T15:48:53Z",
        "sum_avms_uptime": 0.0
    }
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Status Codes:	200 OK – no error 404 Not Found – there is no project identified by project_id, or it exists but does not belong to the user, or the user itself does not exist
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	count_avms (integer) – number of Virtual Machines in the project project_id (uuid) – uuid of the project project_name (uuid) – user-provided name status (string) – one of (QUEUED, CREATING, READY, DELETING, DELETED, ERROR) status_reason (string) – status details (when status=ERROR) status_ts (iso8601) – timestamp of the status sum_avms_uptime (float) – total longevity of the VMs in the project, in seconds

GET /projects/(string: project_id)/apk¶

List the APK files contained in a project.

Example request:

$ http :8084/projects/722de0eeb70011e69093fa163e5f2779/apk

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "apks": [
        {
            "apk_id": "282831ecb71011e69093fa163e5f2779",
            "filename": "com.uberspot.a2048_23.apk",
            "package": "com.uberspot.a2048",
            "project_id": "722de0eeb70011e69093fa163e5f2779",
            "status": "READY",
            "testsource_id": ""
        },
        {
            "apk_id": "8a2d63d2b7a911e69093fa163e5f2779",
            "filename": "com.zenika.aic.core.libs.test-2.apk",
            "package": "com.zenika.aic.core.libs.test",
            "project_id": "722de0eeb70011e69093fa163e5f2779",
            "status": "READY"
            "testsource_id": ""
        }
    ]
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Status Codes:	200 OK – no error 404 Not Found – there is no project identified by project_id, or it exists but does not belong to the user, or the user itself does not exist
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	apk_id (uuid) – the APK identifier filename (string) – the original name of the uploaded file package (string) – package name from AndroidManifest.xml project_id (uuid) – uuid of the project status (string) – one of (QUEUED, UPLOADING, COMPILING DSL, COMPILING JAVA, READY, DELETING, DELETED, ERROR) testsource_id (uuid) – identifier of the test source file (if the apk was compiled) or empty string if the apk was uploaded

GET /projects/(string: project_id)/apk/(string: apk_id)¶

Retrieve information about an APK.

Example request:

$ http :8084/projects/722de0eeb70011e69093fa163e5f2779/apk/282831ecb71011e69093fa163e5f2779

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "apk": {
        "apk_id": "282831ecb71011e69093fa163e5f2779",
        "filename": "com.uberspot.a2048_23.apk",
        "package": "com.uberspot.a2048",
        "project_id": "722de0eeb70011e69093fa163e5f2779",
        "status": "READY",
        "status_reason": ""
    }
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project apk_id – the APK identifier
Status Codes:	200 OK – no error 404 Not Found – there is no project identified by project_id, or no apk identified by apk_id
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	apk_id (uuid) – the APK identifier filename (string) – the original name of the uploaded file package (string) – package name from AndroidManifest.xml project_id (uuid) – uuid of the project status (string) – one of (QUEUED, UPLOADING, COMPILING DSL, COMPILING JAVA, READY, DELETING, DELETED, ERROR) status_reason (string) – status details (when status=ERROR)

GET /projects/(string: project_id)/camera¶

List the camera files contained in a project.

Example request:

$ http :8084/projects/722de0eeb70011e69093fa163e5f2779/camera

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "camera_files": [
        {
            "camera_id": "15a56ea8b87911e69093fa163e5f2779",
            "filename": "ubuntu-logo.png",
            "project_id": "722de0eeb70011e69093fa163e5f2779",
            "status": "READY"
        }
    ]
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Status Codes:	200 OK – no error 404 Not Found – there is no project identified by project_id, or it exists but does not belong to the user, or the user itself does not exist
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	camera_id (uuid) – the camera file identifier filename (string) – the original name of the uploaded file project_id (uuid) – uuid of the project status (string) – one of (UPLOADING, READY, DELETING, DELETED, ERROR)

GET /projects/(string: project_id)/campaigns¶

List the test campaigns in a project.

Example request:

$ http :8084/projects/63f49082dbf811e690e6fa163e15ccce/campaigns

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "campaigns": [
        {
            "campaign_id": "8bbe5d58dc0411e690e6fa163e15ccce",
            "campaign_name": "lovely-big-cobra",
            "project_id": "63f49082dbf811e690e6fa163e15ccce",
            "status": "READY"
        }
    ]
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Status Codes:	200 OK – no error 404 Not Found – there is no project identified by project_id, or it exists but does not belong to the user, or the user itself does not exist
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	campaign_id (uuid) – uuid of the campaign campaign_name (string) – custom (user defined or generated) campaign name status (string) – one of (QUEUED, RUNNING, READY, DELETING, DELETED, ERROR)

GET /projects/(string: project_id)/campaigns/(string: campaign_id)¶

Retrieve information about a test campaign.

Example request:

$ http :8084/projects/63f49082dbf811e690e6fa163e15ccce/campaigns/8bbe5d58dc0411e690e6fa163e15ccce

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "campaign": {
        "campaign_id": "8bbe5d58dc0411e690e6fa163e15ccce",
        "campaign_name": "lovely-big-cobra",
        "campaign_status": "READY",
        "progress": 1.0,
        "project_id": "63f49082dbf811e690e6fa163e15ccce",
        "tests": [
            {
                "hwconfig": {
                    "dpi": 160,
                    "enable_battery": 1,
                    "enable_camera": 1,
                    "enable_gps": 1,
                    "enable_gsm": 1,
                    "enable_nfc": 0,
                    "enable_record": 0,
                    "enable_sensors": 1,
                    "height": 600,
                    "width": 800
                },
                "image": "lollipop-phone",
                "package": "com.zenika.aic.core.libs.test/android.test.InstrumentationTestRunner",
                "status": "READY",
                "stdout": "INSTRUMENTATION_STATUS: numtests=2\nINSTRUMENTATION_STATUS: stream=\ncom.zenika.aic.core.libs.ParserTest [...]"
            }
        ]
    }
}

Request Headers:
	X-Auth-UserId – a user who has access to the campaign
Parameters:	project_id – uuid of the project campaign_id – uuid of the campaign
Status Codes:	200 OK – no error 404 Not Found – there is no project identified by project_id, or no campaign
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	campaign_id (uuid) – uuid of the campaign campaign_name (string) – custom (user defined or generated) campaign name campaign_status (string) – one of (QUEUED, RUNNING, READY, DELETING, DELETED, ERROR) progress (float) – completion status of the campaign hwconfig (object) – the environment configuration for the VM image (string) – Android image used to create the VM package (string) – instrumented test package status (string) – one of (QUEUED, RUNNING, READY, ERROR)

DELETE /projects/(string: project_id)/campaigns/(string: campaign_id)¶

Remove an existing test campaign (either running, or finished).

Example request:

$ http delete :8084/projects/63f49082dbf811e690e6fa163e15ccce/campaigns/8bbe5d58dc0411e690e6fa163e15ccce

Example response:

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: application/octet-stream

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project campaign_id – uuid of the campaign
Status Codes:	204 No Content – the campaign has been deleted

GET /projects/(string: project_id)/testsources¶

List the DSL files in a project.

Example request:

$ http :8084/projects/722de0eeb70011e69093fa163e5f2779/testsources

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "testsources": [
        {
            "apk_id": "0e18f032dca611e690e7fa163e15ccce",
            "apk_status": "READY",
            "apk_status_reason": "",
            "filename": "test1.aic",
            "project_id": "722de0eeb70011e69093fa163e5f2779",
            "status": "READY",
            "testsource_id": "ef8ef4ccdca511e690e7fa163e15ccce"
        },
        {
            "apk_id": "",
            "apk_status": "COMPILING JAVA",
            "apk_status_reason": "",
            "filename": "test2.aic",
            "project_id": "722de0eeb70011e69093fa163e5f2779",
            "status": "READY",
            "testsource_id": "f107efd4dca511e690e7fa163e15ccce"
        },
    ]
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Status Codes:	200 OK – no error 404 Not Found – there is no project identified by project_id, or it exists but does not belong to the user, or the user itself does not exist
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	apk_id (uuid) – the APK identifier (if the file has been compiled), or empty string apk_status (string) – one of (QUEUED, UPLOADING, COMPILING DSL, COMPILING JAVA, READY, DELETING, DELETED, ERROR) apk_status_reason (string) – status details (when apk_status=ERROR) filename (string) – the original name of the uploaded file project_id (uuid) – uuid of the project status (string) – one of (UPLOADING, READY) testsource_id (uuid) – identifier of the test source file

GET /projects/(string: project_id)/testsources/(string: testsource_id)¶

Download the content of a test source (DSL).

Example request:

$ http :8084/projects/722de0eeb70011e69093fa163e5f2779/testsources/eaefe8b8b87911e69093fa163e5f2779

Example response:

HTTP/1.1 200 OK
Content-Length: 204
Content-Type: text/plain; charset=utf-8

Feature: "Best feature ever"
   Scenario: "Best scenario ever"
      Set sensor TYPE_LIGHT at 42
      Take a screenshot
   End

   Scenario: "Worst scenario ever"
      Set battery level at 1
   End
End

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project testsource_id – identifier of the test source file
Status Codes:	200 OK – no error 404 Not Found – there is no project identified by project_id, or no testsource identified by testsource_id
Response Headers:
	Content-Type – always text/plain

GET /projects/(string: project_id)/testsources/(string: testsource_id)/metadata¶

Retrieve information about a test source.

Example request:

$ http :8084/projects/722de0eeb70011e69093fa163e5f2779/testsources/eaefe8b8b87911e69093fa163e5f2779/metadata

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "testsource": {
        "apk_id": "",
        "apk_status": "",
        "apk_status_reason": "",
        "filename": "test.aic",
        "project_id": "722de0eeb70011e69093fa163e5f2779",
        "status": "READY",
        "testsource_id": "eaefe8b8b87911e69093fa163e5f2779"
    }
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project testsource_id – identifier of the test source file
Status Codes:	200 OK – no error 404 Not Found – there is no project identified by project_id, or no testsource identified by testsource_id
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	apk_id (uuid) – the APK identifier (if the file has been compiled), or empty string apk_status (string) – one of (QUEUED, UPLOADING, COMPILING DSL, COMPILING JAVA, READY, DELETING, DELETED, ERROR) apk_status_reason (string) – status details (when apk_status=ERROR) filename (string) – the original name of the uploaded file project_id (uuid) – uuid of the project status (string) – one of (UPLOADING, READY) testsource_id (uuid) – identifier of the test source file

POST /projects¶

Create a project and assign it to the current user.

A positive response means the creation of the project has been started. When the project creation is finalized, its status becomes READY.

Example request:

$ http post :8084/projects project_name=peace

Example response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "project_id": "3d7cff8eb6ff11e69093fa163e5f2779"
}

Request Headers:
	X-Auth-UserId – the user who will own the project
Request JSON Object:
	project_name (string) – user-provided name, need not be unique
Status Codes:	201 Created – the creation of the project has started
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	project_id (uuid) – unique identifier

POST /projects/(string: project_id)/apk¶

Upload an APK file to a project.

Example request:

$ http --form :8084/projects/e8248ab0baf111e69093fa163e5f2779/apk file@com.uberspot.a2048_23.apk

Example response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "apk_id": "5c96b552baf311e69093fa163e5f2779"
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Status Codes:	201 Created – the upload of the apk has started
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	apk_id (uuid) – the APK identifier

POST /projects/(string: project_id)/camera¶

Upload a camera file to a project. The file can be an image or movie, and will be converted if needed.

Example request:

$ http --form :8084/projects/722de0eeb70011e69093fa163e5f2779/camera file@ubuntu-logo.png

Example response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "camera_file_id": "15a56ea8b87911e69093fa163e5f2779"
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Status Codes:	201 Created – the upload/conversion of the media file has started
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	camera_file_id (uuid) – the camera file identifier

POST /projects/(string: project_id)/campaigns¶

Create a test campaign.

Example request:

$ http post :8084/projects/63f49082dbf811e690e6fa163e15ccce/campaigns campaign_name=my-campaign tests:='[{"image":"kitkat-tablet", "hwconfig":{"dpi":160,"enable_battery":1,"enable_camera":1,"enable_gps":1,"enable_gsm":1,"enable_nfc":0,"enable_record":0,"enable_sensors":1,"height":600,"width": 800}, "apks":["54cf0536dbfa11e690e6fa163e15ccce","5b1c0a06dbfa11e690e6fa163e15ccce","10971afadca611e690e7fa163e15ccce"], "packages":["com.example.android.apis","com.android.gesture.builder"]}]'

Example response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8

{
    "campaign_id": "5ee2fbc8dcb211e690e7fa163e15ccce"
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Response JSON Object:
	campaign_name (string) – custom campaign name, will generate one if missing tests (object) – list of testruns to create image (string) – Android image used to create the VM hwconfig (object) – configuration of the VM apks (object) – list of APKs to install packages (object) – list of packages under test campaign_id (uuid) – id of the new test campaign
Status Codes:	202 Accepted – the creation of the campaign has started
Response Headers:
	Content-Type – always application/json

POST /projects/(string: project_id)/testsources¶

Upload a test source to a project.

Example request:

$ http --form :8084/projects/722de0eeb70011e69093fa163e5f2779/testsources file@test.aic

Example response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "testsource_id": "eaefe8b8b87911e69093fa163e5f2779"
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Status Codes:	201 Created – the file has been uploaded
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	testsource_id (uuid) – identifier of the test source file

POST /projects/(string: project_id)/testsources/(string: testsource_id)/apk¶

Compile a test source to an APK file.

Example request:

$ http post :8084/projects/63f49082dbf811e690e6fa163e15ccce/testsources/39c9ad06dca711e690e7fa163e15ccce/apk

Example response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8

{
    "apk_id": "82db80fadca711e690e7fa163e15ccce"
}

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Status Codes:	202 Accepted – the testsource is being compiled
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	apk_id (uuid) – the APK identifier of the test application

PUT /projects/(string: project_id)¶

Changes metadata of a project (currently only the name).

Example request:

$ http put :8084/projects/722de0eeb70011e69093fa163e5f2779 project_name=qwerty

Example response:

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: application/octet-stream

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project
Request JSON Object:
	avm_name (string) – new project name
Status Codes:	204 No Content – the name of the project has been changed

PUT /projects/(string: project_id)/testsources/(string: testsource_id)¶

Update the content of a test source. Filename will be updated too.

Example request:

$ http --form put :8084/projects/722de0eeb70011e69093fa163e5f2779/testsources/eaefe8b8b87911e69093fa163e5f2779 file@test.aic

Example response:

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: application/octet-stream

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project testsource_id – identifier of the test source file
Status Codes:	204 No Content – the content has been updated

DELETE /projects/(string: project_id)¶

Remove a project. Projects can only be removed if they don’t contain running vms or campaigns.

Example request:

$ http delete :8084/projects/3d7cff8eb6ff11e69093fa163e5f2779

Example response:

HTTP/1.1 202 Accepted

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – the identifier of the project to remove
Status Codes:	202 Accepted – the removal of the project has started 404 Not Found – the project does not exist, or the user cannot access it, or the user does not exist

DELETE /projects/(string: project_id)/apk/(string: apk_id)¶

Delete an APK file from a project.

Example request:

$ http delete :8084/projects/722de0eeb70011e69093fa163e5f2779/apk/282831ecb71011e69093fa163e5f2779

Example response:

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: application/octet-stream

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project apk_id – the APK file to remove
Status Codes:	204 No Content – the APK file has been deleted

DELETE /projects/(string: project_id)/camera/(string: camera_file_id)¶

Delete a camera file from a project.

Example request:

$ http delete :8084/projects/722de0eeb70011e69093fa163e5f2779/camera/15a56ea8b87911e69093fa163e5f2779

Example response:

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: application/octet-stream

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project camera_file_id – the camera file to remove
Status Codes:	204 No Content – the camera file has been deleted

DELETE /projects/(string: project_id)/testsources/(string: testsource_id)¶

Delete a test source from a project.

Example request:

$ http delete :8084/projects/722de0eeb70011e69093fa163e5f2779/testsources/eaefe8b8b87911e69093fa163e5f2779

Example response:

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: application/octet-stream

Request Headers:
	X-Auth-UserId – a user who has access to the project
Parameters:	project_id – uuid of the project testsource_id – the test source to remove
Status Codes:	204 No Content – the test source has been deleted

GET /user/quota¶

Quota consumption and limits for the current user.

Example request:

$ http :8084/user/quota

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "quota": {
        "vm_async_current": 0,
        "vm_async_max": 3,
        "vm_live_current": 0,
        "vm_live_max": 3
    }
}

Request Headers:
	X-Auth-UserId – a user who needs to know its quota consumption
Status Codes:	200 OK – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	vm_async_current (integer) – current total of vms running a test campaign vm_async_max (integer) – maximum number of concurrent vms in test campaigns vm_live_current (integer) – current total of live vms for the user vm_live_max (integer) – maximum number of concurrent live vms

GET /user/whoami¶

Information about the current user. Currently only the user id, which a frontend may not know if it authenticates with an opaque token.

Example request:

$ http :8084/user/whoami

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "user": {
        "userid": "marco"
    }
}

Request Headers:
	X-Auth-UserId – a user
Status Codes:	200 OK – no error
Response Headers:
	Content-Type – always application/json
Response JSON Object:
	userid (string) – the unique user identifier