Over-the-air orchestrator REST 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.

get
get

Returns software by application name.

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

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

HTTP status code 200

List of objects with software details.

Body

Media type: application/json

Type: array of otao-api-types.SoftwareResponse

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 string)

    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 otao-api-types.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.

  • filename: (string)

    Software file name.

Example:

[
  {
    "appName": "smart-kettle",
    "version": "1.0.2",
    "specification": {
      "link": "ftp://software-repository"
    },
    "metadata": "Ubuntu 17.10",
    "upgradableFrom": [
      "1.0.0",
      "1.0.1"
    ],
    "filename": "sketch.bin",
    "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.

get put post delete
get

Returns software by application name and software version.

put

Updates software.

post

Creates software.

delete

Deletes software if it is not used by any endpoint.

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

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

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 string)

    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 otao-api-types.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.

  • filename: (string)

    Software file name.

Example:

{
  "appName": "smart-kettle",
  "version": "1.0.2",
  "specification": {
    "link": "ftp://software-repository"
  },
  "metadata": "Ubuntu 17.10",
  "upgradableFrom": [
    "1.0.0",
    "1.0.1"
  ],
  "filename": "sketch.bin",
  "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.

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

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

Body

Media type: application/json

Type: object

Properties
  • metadata: (any)

    Software metadata. Could be of any valid JSON type.

  • upgradableFrom: (array of string)

    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 otao-api-types.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.

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

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

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 string)

    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 otao-api-types.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.

Deletes software if it is not used by any endpoint.

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

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

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

HTTP status code 204

Software deleted successfully.

HTTP status code 400

Invalid request.

Body

Media type: application/json

Type: object

Properties
  • message: required(string)

    Detailed error description.

HTTP status code 403

User does not have permissions to perform this operation.

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
put

Uploads software file. Link to the uploaded file will be attached to the software specification when sending to the endpoint that is eligible for upgrading to that software version. File name must be non-empty, contain only a-z0-9-._ symbols, and have length from 1 to 30 symbols.

Uploads software file. Link to the uploaded file will be attached to the software specification when sending to the endpoint that is eligible for upgrading to that software version. File name must be non-empty, contain only a-z0-9-._ symbols, and have length from 1 to 30 symbols.

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

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

Body

Media type: multipart/form-data

Type: object

Properties
  • file: required(string)

    File to upload.

HTTP status code 204

Software file is successfully uploaded.

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.

delete
delete

Deletes software file.

Deletes software file.

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

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
  • fileName: required(string)

    Software file name.

    Example:

    app.bin

HTTP status code 204

Software file deleted successfully.

HTTP status code 403

User does not have permissions to perform this operation.

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.

get
get

Generates and returns software file donwload link with expiration time specified in the service configuration.

Generates and returns software file donwload link with expiration time specified in the service configuration.

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
  • fileName: required(string)

    Software file name.

    Example:

    app.bin

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

HTTP status code 200

Software file download link is sucessfully generated.

Body

Media type: application/json

Type: object

Properties
  • link: required(string)

    Software file download link.

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.

get
get

Returns current software of a specified endpoint.

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

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

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 string)

    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 otao-api-types.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.

  • filename: (string)

    Software file name.

Example:

{
  "appName": "smart-kettle",
  "version": "1.0.2",
  "specification": {
    "link": "ftp://software-repository"
  },
  "metadata": "Ubuntu 17.10",
  "upgradableFrom": [
    "1.0.0",
    "1.0.1"
  ],
  "filename": "sketch.bin",
  "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.