REST API

Over-the-air orchestrator REST API documentation version v1

{schema}://{host}/api/{version}

  • schema: required (one of http, https - default: http)
  • host: required (string - default: localhost)
  • version: required (v1)

Application software

Operations on software.

/applications/{appName}/software get

get /applications/{appName}/software

Returns software by application name.

Secured by oauth_2_0 with scopes:
  • application:software:read

OTAO supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • appName: required (string)

    Application name that software is attributed to.

    Example:

    smart-kettle

HTTP status code 200

List of objects with software details.

Body

Media type: application/json

Type: array of Software

Items: Software

  • specification: (any)

    Software specification that is sent to endpoint. Could be of any valid JSON type.

  • metadata: (any)

    Software metadata. Could be of any valid JSON type.

  • upgradableFrom: (array of items)

    The list of software versions that can be upgraded to this one.

  • rolloutStrategy: required (one of suspended, targeted, general)

    Specifies the software rollout strategy.

    • `suspended` - the rollout is disabled, no endpoints receive the software.
    • `targeted` - the rollout is performed based on the software compatibility graph and endpoint filters.
    • `general` - the rollout is performed based on the software compatibility graph alone, no recipient endpoint filtering occurs.
  • filters: (array of Filter)

    The list of endpoint filters used by the targeted rollout strategy. Only the endpoints that match at least one of the specified filters and filter's rollout date was overdue are eligible for receiving the software update.

    Items: Filter

    • filterId: required (string)

      filter identifier.

    • rolloutDate: (datetime)

      Filter activation date. Must be in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'.

  • appName: required (string)

    Application name that software is attributed to.

  • version: required (string)

    Software semantic version. Unique in an application scope. Is used for software priority regulation.

Example:

[
  {
    "appName":"smart-kettle",
    "version":"1.0.2",
    "specification":{
      "link":"ftp://software-repository"
    },
    "metadata":"Ubuntu 17.10",
    "upgradableFrom":[
      "1.0.0",
      "1.0.1"
    ],
    "rolloutStrategy": "targeted",
    "filters":[
      {
        "filterId" : "79c717d9-eedd-4f71-b9f8-86caf7e309e4",
        "rolloutDate" : "2019-04-20T11:19:57.848Z"
      },
      {
        "filterId" : "14ebc071-31f8-4137-b60f-6e83b0f8299c",
        "rolloutDate" : "2019-05-20T11:19:57.848Z"
      }
    ]
  },
  {
    "appName":"smart-kettle",
    "version":"1.2.3",
    "specification":{
      "link":"ftp://software-repository"
    },
    "metadata":"Ubuntu 16.04",
    "upgradableFrom":[
      "1.2.2"
    ],
    "rolloutStrategy": "general",
    "filters":[]
  }
]

HTTP status code 400

Invalid request.

Body

Media type: application/json

Type: object

Properties

  • message: required (string)

    Detailed error description.

HTTP status code 404

Application name not found or user does not have permissions to perform this operation.

Body

Media type: application/json

Type: object

Properties

  • message: required (string)

    Detailed error description.

Secured by oauth_2_0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

/applications/{appName}/software/{softwareVersion} get put post

get /applications/{appName}/software/{softwareVersion}

Returns software by application name and software version.

Secured by oauth_2_0 with scopes:
  • application:software:read

OTAO supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • appName: required (string)

    Application name that software is attributed to.

    Example:

    smart-kettle
  • softwareVersion: required (string)

    Software semantic version. Unique in an application scope. Is used for software priority regulation.

    Example:

    1.0.2

HTTP status code 200

Software response.

Body

Media type: application/json

Type: object

Properties

  • specification: (any)

    Software specification that is sent to endpoint. Could be of any valid JSON type.

  • metadata: (any)

    Software metadata. Could be of any valid JSON type.

  • upgradableFrom: (array of items)

    The list of software versions that can be upgraded to this one.

  • rolloutStrategy: required (one of suspended, targeted, general)

    Specifies the software rollout strategy.

    • `suspended` - the rollout is disabled, no endpoints receive the software.
    • `targeted` - the rollout is performed based on the software compatibility graph and endpoint filters.
    • `general` - the rollout is performed based on the software compatibility graph alone, no recipient endpoint filtering occurs.
  • filters: (array of Filter)

    The list of endpoint filters used by the targeted rollout strategy. Only the endpoints that match at least one of the specified filters and filter's rollout date was overdue are eligible for receiving the software update.

    Items: Filter

    • filterId: required (string)

      filter identifier.

    • rolloutDate: (datetime)

      Filter activation date. Must be in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'.

  • appName: required (string)

    Application name that software is attributed to.

  • version: required (string)

    Software semantic version. Unique in an application scope. Is used for software priority regulation.

Example:

{
  "appName":"smart-kettle",
  "version":"1.0.2",
  "specification":{
    "link":"ftp://software-repository"
  },
  "metadata":"Ubuntu 17.10",
  "upgradableFrom":[
    "1.0.0",
    "1.0.1"
  ],
  "rolloutStrategy": "targeted",
  "filters":[
    {
      "filterId" : "79c717d9-eedd-4f71-b9f8-86caf7e309e4",
      "rolloutDate" : "2019-04-20T11:19:57.848Z"
    },
    {
      "filterId" : "14ebc071-31f8-4137-b60f-6e83b0f8299c",
      "rolloutDate" : "2019-05-20T11:19:57.848Z"
    }
  ]
}

HTTP status code 400

Invalid request.

Body

Media type: application/json

Type: object

Properties

  • message: required (string)

    Detailed error description.

HTTP status code 404

Application name or software version not found or user does not have permissions to perform this operation.

Body

Media type: application/json

Type: object

Properties

  • message: required (string)

    Detailed error description.

Secured by oauth_2_0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

put /applications/{appName}/software/{softwareVersion}

Updates software.

Secured by oauth_2_0 with scopes:
  • application:software:update

OTAO supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • appName: required (string)

    Application name that software is attributed to.

    Example:

    smart-kettle
  • softwareVersion: required (string)

    Software semantic version. Unique in an application scope. Is used for software priority regulation.

    Example:

    1.0.2

Body

Media type: application/json

Type: object

Properties

  • metadata: (any)

    Software metadata. Could be of any valid JSON type.

  • upgradableFrom: (array of items)

    The list of software versions that can be upgraded to this one.

  • rolloutStrategy: required (one of suspended, targeted, general)

    Specifies the software rollout strategy.

    • `suspended` - the rollout is disabled, no endpoints receive the software.
    • `targeted` - the rollout is performed based on the software compatibility graph and endpoint filters.
    • `general` - the rollout is performed based on the software compatibility graph alone, no recipient endpoint filtering occurs.
  • filters: (array of Filter)

    The list of endpoint filters used by the targeted rollout strategy. Only the endpoints that match at least one of the specified filters and filter's rollout date was overdue are eligible for receiving the software update.

    Items: Filter

    • filterId: required (string)

      filter identifier.

    • rolloutDate: (datetime)

      Filter activation date. Must be in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'.

Example:

{
  "metadata":"Ubuntu 17.10",
  "upgradableFrom":[
    "1.0.0",
    "1.0.1"
  ],
  "rolloutStrategy": "targeted",
  "filters":[
    {
      "filterId" : "79c717d9-eedd-4f71-b9f8-86caf7e309e4",
      "rolloutDate" : "2019-04-20T11:19:57.848Z"
    },
    {
      "filterId" : "14ebc071-31f8-4137-b60f-6e83b0f8299c",
      "rolloutDate" : "2019-05-20T11:19:57.848Z"
    }
  ]
}

HTTP status code 204

Software updated successfully.

HTTP status code 400

Invalid request.

Body

Media type: application/json

Type: object

Properties

  • message: required (string)

    Detailed error description.

HTTP status code 404

Application name or software version not found or user does not have permissions to perform this operation.

Body

Media type: application/json

Type: object

Properties

  • message: required (string)

    Detailed error description.

Secured by oauth_2_0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

post /applications/{appName}/software/{softwareVersion}

Creates software.

Secured by oauth_2_0 with scopes:
  • application:software:update

OTAO supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • appName: required (string)

    Application name that software is attributed to.

    Example:

    smart-kettle
  • softwareVersion: required (string)

    Software semantic version. Unique in an application scope. Is used for software priority regulation.

    Example:

    1.0.2

Body

Media type: application/json

Type: object

Properties

  • specification: (any)

    Software specification that is sent to endpoint. Could be of any valid JSON type.

  • metadata: (any)

    Software metadata. Could be of any valid JSON type.

  • upgradableFrom: (array of items)

    The list of software versions that can be upgraded to this one.

  • rolloutStrategy: required (one of suspended, targeted, general)

    Specifies the software rollout strategy.

    • `suspended` - the rollout is disabled, no endpoints receive the software.
    • `targeted` - the rollout is performed based on the software compatibility graph and endpoint filters.
    • `general` - the rollout is performed based on the software compatibility graph alone, no recipient endpoint filtering occurs.
  • filters: (array of Filter)

    The list of endpoint filters used by the targeted rollout strategy. Only the endpoints that match at least one of the specified filters and filter's rollout date was overdue are eligible for receiving the software update.

    Items: Filter

    • filterId: required (string)

      filter identifier.

    • rolloutDate: (datetime)

      Filter activation date. Must be in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'.

Example:

{
  "specification":{
    "link":"ftp://software-repository"
  },
  "metadata":"Ubuntu 17.10",
  "upgradableFrom":[
    "1.0.0",
    "1.0.1"
  ],
  "rolloutStrategy": "targeted",
  "filters":[
    {
      "filterId" : "79c717d9-eedd-4f71-b9f8-86caf7e309e4",
      "rolloutDate" : "2019-04-20T11:19:57.848Z"
    },
    {
      "filterId" : "14ebc071-31f8-4137-b60f-6e83b0f8299c",
      "rolloutDate" : "2019-05-20T11:19:57.848Z"
    }
  ]
}

HTTP status code 201

Software created successfully.

Headers

  • Location: required (string)

    Location of newly created software.

    Example:

    http://example.com/api/v1/applications/smart-kettle/software/versions/1.0.2

HTTP status code 400

Invalid request.

Body

Media type: application/json

Type: object

Properties

  • message: required (string)

    Detailed error description.

HTTP status code 404

Application name or software version not found or user does not have permissions to perform this operation.

Body

Media type: application/json

Type: object

Properties

  • message: required (string)

    Detailed error description.

Secured by oauth_2_0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

Endpoint software

Operations on compatible software with endpoints and consents regarding its installation.

/endpoints/{endpointId}/software/current get

get /endpoints/{endpointId}/software/current

Returns current software of a specified endpoint.

Secured by oauth_2_0 with scopes:
  • endpoint:read

OTAO supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • endpointId: required (string)

    Unique endpoint identifier

    Example:

    7d5dda9b-c9f6-427d-91ea-9891a4f62cbb

HTTP status code 200

Software response.

Body

Media type: application/json

Type: object

Properties

  • specification: (any)

    Software specification that is sent to endpoint. Could be of any valid JSON type.

  • metadata: (any)

    Software metadata. Could be of any valid JSON type.

  • upgradableFrom: (array of items)

    The list of software versions that can be upgraded to this one.

  • rolloutStrategy: required (one of suspended, targeted, general)

    Specifies the software rollout strategy.

    • `suspended` - the rollout is disabled, no endpoints receive the software.
    • `targeted` - the rollout is performed based on the software compatibility graph and endpoint filters.
    • `general` - the rollout is performed based on the software compatibility graph alone, no recipient endpoint filtering occurs.
  • filters: (array of Filter)

    The list of endpoint filters used by the targeted rollout strategy. Only the endpoints that match at least one of the specified filters and filter's rollout date was overdue are eligible for receiving the software update.

    Items: Filter

    • filterId: required (string)

      filter identifier.

    • rolloutDate: (datetime)

      Filter activation date. Must be in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'.

  • appName: required (string)

    Application name that software is attributed to.

  • version: required (string)

    Software semantic version. Unique in an application scope. Is used for software priority regulation.

Example:

{
  "appName":"smart-kettle",
  "version":"1.0.2",
  "specification":{
    "link":"ftp://software-repository"
  },
  "metadata":"Ubuntu 17.10",
  "upgradableFrom":[
    "1.0.0",
    "1.0.1"
  ],
  "rolloutStrategy": "targeted",
  "filters":[
    {
      "filterId" : "79c717d9-eedd-4f71-b9f8-86caf7e309e4",
      "rolloutDate" : "2019-04-20T11:19:57.848Z"
    },
    {
      "filterId" : "14ebc071-31f8-4137-b60f-6e83b0f8299c",
      "rolloutDate" : "2019-05-20T11:19:57.848Z"
    }
  ]
}

HTTP status code 404

Software or given endpoint not found or user does not have permissions to perform this operation.

Body

Media type: application/json

Type: object

Properties

  • message: required (string)

    Detailed error description.

Secured by oauth_2_0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.