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 : docker.mender.io
BasePath : /api/devices/v1/deployments
Schemes : HTTPS

Paths


Get a next update

GET /device/deployments/next

Description

Returns a next update to be installed on the device.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the Device Authentication Service. string(Bearer [token])
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
404 Not Found. Error
500 Internal Server Error. Error

Produces

  • application/json

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "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 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "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 Default
Header Authorization
required
Contains the JWT token issued by the Device Authentication Service. string(Bearer [token])
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

Produces

  • application/json

Example HTTP request

Request body
json :
{
  "application/json" : {
    "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
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "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 Default
Header Authorization
required
Contains the JWT token issued by the Device Authentication Service. string(Bearer [token])
Path id
required
Deployment identifier. string
Body Status
required
Deployment status. Status

Status

Name Description Schema
status
required
enum (installing, downloading, rebooting, success, failure, already-installed)

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

Produces

  • application/json

Example HTTP response

Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "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

DeploymentLog

Name Description Schema
messages
required
< messages > array

messages

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

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