Here is
new documentation version.
You are reading outdated documentation, which will be shutdown soon!
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.
- 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: optional (any)
Software specification that is sent to endpoint. Could be of any valid JSON type.
- metadata: optional (any)
Software metadata. Could be of any valid JSON type.
- upgradableFrom: optional (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: optional (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: optional (datetime)
Filter activation date. Must be in the following ISO 8601 format:
yyyy-MM-dd'T'HH:mm:ss'Z'
.
- filterId: required(string)
- 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: optional (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 /applications/{appName}/software/{softwareVersion}
Returns software by application name and software version.
- 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: optional (any)
Software specification that is sent to endpoint. Could be of any valid JSON type.
- metadata: optional (any)
Software metadata. Could be of any valid JSON type.
- upgradableFrom: optional (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: optional (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: optional (datetime)
Filter activation date. Must be in the following ISO 8601 format:
yyyy-MM-dd'T'HH:mm:ss'Z'
.
- filterId: required(string)
- 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: optional (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.
- 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: optional (any)
Software metadata. Could be of any valid JSON type.
- upgradableFrom: optional (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: optional (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: optional (datetime)
Filter activation date. Must be in the following ISO 8601 format:
yyyy-MM-dd'T'HH:mm:ss'Z'
.
- filterId: required(string)
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: optional (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.
- 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: optional (any)
Software specification that is sent to endpoint. Could be of any valid JSON type.
- metadata: optional (any)
Software metadata. Could be of any valid JSON type.
- upgradableFrom: optional (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: optional (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: optional (datetime)
Filter activation date. Must be in the following ISO 8601 format:
yyyy-MM-dd'T'HH:mm:ss'Z'
.
- filterId: required(string)
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: optional (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.
- 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: optional (any)
Software specification that is sent to endpoint. Could be of any valid JSON type.
- metadata: optional (any)
Software metadata. Could be of any valid JSON type.
- upgradableFrom: optional (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: optional (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: optional (datetime)
Filter activation date. Must be in the following ISO 8601 format:
yyyy-MM-dd'T'HH:mm:ss'Z'
.
- filterId: required(string)
- 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: optional (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.