Anbox HTTP API

Anbox provides an HTTP API endpoint through a Unix socket at /run/users/1000/anbox/api.socket inside every container. The API allows controlling certain aspects of the Anbox runtime and the Android container.

Accessing the API endpoint

The API endpoint can be for example accessed via curl in the following way

$ curl --unix-socket /run/user/1000/anbox/sockets/api.unix s/1.0

API versioning

When Android container gets up and running, all REST API endpoints are served under the base path /1.0/ inside of the container.

The details of a version of the api can be retrieved using GET s/1.0.

The reason for a major API bump is if the API breaks backward compatibility.

Feature additions are done without breaking backward compatibility only result in addition to api_extensions which can be used by the client to check if a given feature is supported by the server.

Return values

There are two standard return types:

  • Standard return value
  • Error

Standard return value

For standard synchronous operation, the following dict is returned:

{
    "type": "sync",        # Standard operation type ("sync" or "async")
    "status": "Success",   # Response status
    "status_code": 200,    # Response status code
    "metadata": {}         # Extra resource/action specific metadata
}

HTTP code must be 200.

Error

There are various situations in which something may immediately go
wrong, in those cases, the following return value is used:

{
    "type": "error",
    "error": "API endpoint does not exist",
    "error_code": 400,
}

HTTP code must be one of 400 or 500.

API structure

API details

/1.0/

GET

  • Description: Server configuration
  • Operation: sync
  • Steps:
    • Fetch general information of the server
  • Return: Dict representing server state

Return value:

{
    "metadata": {
        "api_extensions": [],         # List of API extensions added after the API was marked stable
        "api_status": "stable",       # API implementation status (one of, development, stable or deprecated)
        "api_version": "1.0"          # The API version as a string
    },
    "status": "Success",
    "status_code": 200,
    "type": "sync"
}

/1.0/location

GET

  • Description: Get location status
  • Operation: sync
  • Return: Current location status

NOTE: After enabling the location endpoint, any location updates provided via the Anbox Platform API won’t be processed by Anbox until the location endpoint is disabled again.

Return value:

{
    "metadata": {
      "enabled": true
    },
    "status": "Success",
    "status_code": 200,
    "type": "sync"
}

POST

  • Description: Activate or deactivate location updates
  • Operation: sync
  • Return: standard return value or standard error

NOTE: Location updates must be activated before posting any location data to Anbox via the PATCH method. If location updates are disabled, requests to provide updates to the Anbox HTTP API will fail.

Input:

{
    "enable": true
}

Return value:

{
    "status": "Success",
    "status_code": 200,
    "type": "sync"
}

PATCH

  • Description: Provide location update to be forwarded to Android
  • Operation: sync
  • Return: standard return value or standard error

NOTE: The latitude or longitude of geographic coordinates is expressed in decimal degree form (WGS84 data format) as shown below in the example, whereas the NMEA-based data format is expressed in ddmm.mm (d refers to degrees, m refers to minutes). No matter which format you use, northern latitudes or eastern longitudes are positive, southern latitudes or western longitudes are negative.

Input:

{
    "latitude":: 52.4538982,         # Latitude of geographic coordinates
    "longitude": 13.3857982,         # Longitude of geographic coordinates
    "altitude": 10.0,                # Altitude in meters
    "time": 1597237057,              # Current time in millisecond since 1970-01-01 00:00:00 UTC
    "speed": 0.0,                    # Speed in meters per second
    "bearing": 0.0,                  # Magnetic heading in degrees
    "format": "wgs84"                # (optional) Location format; possible values are "nmea" or "wgs84". Defaults to "wgs84" if not specified
}

Return value:

{
    "status": "Success",
    "status_code": 200,
    "type": "sync"
}