You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 2.3.

Deployments

Overview

An API for device firmware deployments. Intended for use by devices.

Devices can get new updates and send information about current deployment status.

Version information

Version : 1

URI scheme

Host : hosted.mender.io
BasePath : /api/devices/v1/deployments
Schemes : HTTPS

Consumes

  • application/json

Produces

  • application/json

Paths


Get a next update satisfying dependencies

POST /device/deployments/next

Description

Returns a next update to be installed on the device. Next update will be chosen based on parameters provided in the request body. Request body should contain artifact_provides object.

Parameters

Type Name Description Schema
Body artifact_provides
required
Key-value map of strings which describes the artifact(s) installed on the device and the
device itself. It is used to determine the next deployment. The keys device_type and
artifact_name are mandatory, additional free-form key-value pairs can be specified.
artifact_provides

artifact_provides

Name Description Schema
artifact_name
required
Name of the currently installed artifact. string
device_type
required
Device type of the device. string

Responses

HTTP Code Description Schema
200 Successful response. DeploymentInstructions
204 No updates for device. No Content
400 Invalid Request. Error
404 Not Found. Error
500 Internal Server Error. Error

Produces

  • application/json

Tags

  • Device API

Security

Type Name
apiKey DeviceJWT

Example HTTP response

Response 200
{
  "id" : "w81s4fae-7dec-11d0-a765-00a0c91e6bf6",
  "artifact" : {
    "artifact_name" : "my-app-0.1",
    "source" : {
      "uri" : "https://aws.my_update_bucket.com/image_123",
      "expire" : "2016-03-11T13:03:17.063+0000"
    },
    "device_types_compatible" : [ "rspi", "rspi2", "rspi0" ]
  }
}
Response 400
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Get next update

GET /device/deployments/next

Description

On success, either an empty response or a DeploymentInstructions object is returned depending on whether there are any pending updates.

Parameters

Type Name Description Schema
Query artifact_name
required
currently installed artifact string
Query device_type
required
Device type of device string

Responses

HTTP Code Description Schema
200 Successful response. DeploymentInstructions
204 No updates for device. No Content
400 Invalid Request. Error
404 Not Found. Error
500 Internal Server Error. Error

Tags

  • Device API

Security

Type Name
apiKey DeviceJWT

Example HTTP response

Response 200
{
  "id" : "w81s4fae-7dec-11d0-a765-00a0c91e6bf6",
  "artifact" : {
    "artifact_name" : "my-app-0.1",
    "source" : {
      "uri" : "https://aws.my_update_bucket.com/image_123",
      "expire" : "2016-03-11T13:03:17.063+0000"
    },
    "device_types_compatible" : [ "rspi", "rspi2", "rspi0" ]
  }
}
Response 400
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Upload the device deployment log

PUT /device/deployments/{id}/log

Description

Set the log of a selected deployment. Messages are split by line in the payload.

Parameters

Type Name Description Schema
Path id
required
Deployment identifier. string
Body Log
required
Deployment log DeploymentLog

Responses

HTTP Code Description Schema
204 The deployment log uploaded successfully. No Content
400 Invalid Request. Error
404 Not Found. Error
500 Internal Server Error. Error

Tags

  • Device API

Security

Type Name
apiKey DeviceJWT

Example HTTP request

Request body
{
  "messages" : [ {
    "timestamp" : "2016-03-11T13:03:17.063+0000",
    "level" : "INFO",
    "message" : "OK"
  }, {
    "timestamp" : "2016-03-11T13:03:18.024+0000",
    "level" : "DEBUG",
    "message" : "successfully updated."
  } ]
}

Example HTTP response

Response 400
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Update the device deployment status

PUT /device/deployments/{id}/status

Description

Updates the status of a deployment on a particular device. Final status of the deployment is required to be set to indicate the success or failure of the installation process. The status can not be changed when deployment status is set to aborted. Reporting of intermediate steps such as installing, downloading, rebooting is optional.

Parameters

Type Name Description Schema
Path id
required
Deployment identifier. string
Body Status
required
Deployment status. DeploymentStatus

Responses

HTTP Code Description Schema
204 Status updated successfully. No Content
400 Invalid Request. Error
404 Not Found. Error
409 Status already set to aborted. No Content
500 Internal Server Error. Error

Tags

  • Device API

Security

Type Name
apiKey DeviceJWT

Example HTTP request

Request body
{
  "status" : "success"
}

Example HTTP response

Response 400
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Definitions

DeploymentInstructions

Name Description Schema
artifact
required
artifact
id
required
Deployment ID (device unique) string

artifact

Name Description Schema
artifact_name
required
string
device_types_compatible
required
Compatible device types < string > array
source
required
source

source

Name Description Schema
expire
optional
URL expiration time string (date-time)
uri
optional
URL to fetch the artifact from string (url)

DeploymentLog

Name Schema
messages
required
< messages > array

messages

Name Schema
level
required
string
message
required
string
timestamp
required
string (date-time)

DeploymentStatus

Name Description Schema
status
required
enum (installing, downloading, rebooting, success, failure, already-installed)
substate
optional
Additional state information string

Error

Error descriptor.

Name Description Schema
error
optional
Description of the error. string
request_id
optional
Request ID (same as in X-MEN-RequestID header). string

Security

DeviceJWT

API token issued by Device Authentication service. Format: 'Authorization: Bearer [JWT]'

Type : apiKey
Name : Authorization
In : HEADER