SDU Server API API Reference

The SDU API enables Maintainers, Managers and Devices to interact with the SDU server. The server manages updates with two types of data: The BLOB (Binary Large Object), which holds the data of an update, and a Manifest that assigns product type, version and signature to a BLOB.

API Endpoint

https://[customer]-sdu.ssv-service.de/v2

Contact: jfi@ssv-embedded.de

Schemes: https

Version: 2.1.0

Maintainer

Maintainer Manager

Get a list of present BLOBs

GET /blob

200 OK

BlobList

List of present blobs

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "blobs": [
    {
      "sha256": "string",
      "date": "string (date-time)",
      "size": "integer",
      "maintainer": "string",
      "referencedByVersion": "boolean"
    }
  ]
}

Maintainer Manager

Get info about existing BLOB

GET /blob/{sha256}

sha256: string

in path

SHA256 of the BLOB

200 OK

BlobInfo

Version

404 Not Found

Error

Blob does not exist

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "blob": {
    "sha256": "string",
    "date": "string (date-time)",
    "size": "integer",
    "maintainer": "string",
    "referencedByVersion": "boolean"
  }
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Maintainer

Upload a new BLOB

POST /blob/{sha256}

sha256: string

in path

SHA256 of the content

200 OK

Success

The data has been accepted

400 Bad Request

Error

SHA256 mismatch

409 Conflict

Error

Blob already existing

413 Request Entity Too Large

Error

Blob too large

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer"
}

Response Example (400 Bad Request)

{
  "code": "integer",
  "error": "string"
}

Response Example (409 Conflict)

{
  "code": "integer",
  "error": "string"
}

Response Example (413 Request Entity Too Large)

{
  "code": "integer",
  "error": "string"
}

Maintainer Manager

Delete an existing BLOB

DELETE /blob/{sha256}

sha256: string

in path

SHA256 of the content

200 OK

Success

The blob has been delete

400 Bad Request

Error

Blob is referenced by a version

404 Not Found

Error

Blob does not exist

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer"
}

Response Example (400 Bad Request)

{
  "code": "integer",
  "error": "string"
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Devices Maintainer Manager

Download an existing BLOB

GET /blob/{sha256}/data

sha256: string

in path

SHA256 of the BLOB

200 OK

Data

404 Not Found

Blob does not exist

Response Content-Types: application/octet-stream

Maintainer Devices Manager

Get the delta between a known BLOB and a desired BLOB

GET /blob/{sha256}/xdeltadiff/{knownfilesha256}

sha256: string

in path

SHA256 of the desired BLOB

knownfilesha256: string

in path

SHA256 of the known BLOB

200 OK

The xdelta3 diff to the given hash

404 Not Found

Blob does not exist

428 Precondition Required

Blob with the given knownfilesha256 does not exist

Response Content-Types: application/octet-stream

Manager Maintainer

Get a list of all products

GET /product

200 OK

ProductList

Current version assignment

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "products": [
    "string"
  ]
}

Manager Maintainer

Get a list of all existing versions for a product

GET /product/{product}/version

product: string

in path

Product Name

200 OK

VersionList

Maintainer

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "versions": [
    {
      "date": "string (date-time)",
      "name": "string",
      "maintainer": "string",
      "available": "boolean"
    }
  ]
}

Manager Maintainer

Get information about a version

GET /product/{product}/version/{version}

product: string

in path

Product Name

version: string

in path

Version Name

200 OK

VersionInfo

Version

404 Not Found

Error

Version not found

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "version": {
    "date": "string (date-time)",
    "name": "string",
    "maintainer": "string",
    "available": "boolean"
  }
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Maintainer Manager Devices

Download the version's manifest

GET /product/{product}/version/{version}/manifest

product: string

in path

Product Name

version: string

in path

Version Name

200 OK

The version's mainfest file

404 Not Found

Version not found

Response Content-Types: application/cms

Response Headers (200 OK)


X-Upload-Date	Upload date as Unix timestamp	integer

Maintainer

Upload the version's manifest

POST /product/{product}/version/{version}/manifest

product: string

in path

Product Name

version: string

in path

Version Name

Request Content-Types: application/cms

Request Example

"string"

200 OK

The data has been accepted

400 Bad Request

Error

The version already exists or the manifest is invalid

Response Example (400 Bad Request)

{
  "code": "integer",
  "error": "string"
}

Manager

Maintainer Manager

Get a list of present BLOBs

GET /blob

200 OK

BlobList

List of present blobs

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "blobs": [
    {
      "sha256": "string",
      "date": "string (date-time)",
      "size": "integer",
      "maintainer": "string",
      "referencedByVersion": "boolean"
    }
  ]
}

Maintainer Manager

Get info about existing BLOB

GET /blob/{sha256}

sha256: string

in path

SHA256 of the BLOB

200 OK

BlobInfo

Version

404 Not Found

Error

Blob does not exist

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "blob": {
    "sha256": "string",
    "date": "string (date-time)",
    "size": "integer",
    "maintainer": "string",
    "referencedByVersion": "boolean"
  }
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Maintainer Manager

Delete an existing BLOB

DELETE /blob/{sha256}

sha256: string

in path

SHA256 of the content

200 OK

Success

The blob has been delete

400 Bad Request

Error

Blob is referenced by a version

404 Not Found

Error

Blob does not exist

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer"
}

Response Example (400 Bad Request)

{
  "code": "integer",
  "error": "string"
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Devices Maintainer Manager

Download an existing BLOB

GET /blob/{sha256}/data

sha256: string

in path

SHA256 of the BLOB

200 OK

Data

404 Not Found

Blob does not exist

Response Content-Types: application/octet-stream

Maintainer Devices Manager

Get the delta between a known BLOB and a desired BLOB

GET /blob/{sha256}/xdeltadiff/{knownfilesha256}

sha256: string

in path

SHA256 of the desired BLOB

knownfilesha256: string

in path

SHA256 of the known BLOB

200 OK

The xdelta3 diff to the given hash

404 Not Found

Blob does not exist

428 Precondition Required

Blob with the given knownfilesha256 does not exist

Response Content-Types: application/octet-stream

Manager Maintainer

Get a list of all products

GET /product

200 OK

ProductList

Current version assignment

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "products": [
    "string"
  ]
}

Devices Manager

Get the current version

GET /product/{product}/currentVersion

product: string

in path

Product Name

serialnumber: string

in query

Managers must state a serialnumber get the right version info. For devices this parameter is ignored and the common name of the device's certificate is used instead.

installedVersion: string

in query

Give information about the currently installed version. This will be written to the SDU server's log.

200 OK

CurrentVersion

Current version assignment

404 Not Found

Error

No assignment available for this product or serialnumber

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "currentVersion": {
    "date": "string (date-time)",
    "manager": "string",
    "name": "string"
  }
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Manager

Get the current version assignment

GET /product/{product}/currentVersionAssignment

product: string

in path

Product Name

200 OK

CurrentVersionAssignmentList

Current assignments

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "currentVersionAssignments": [
    {
      "id": "string",
      "date": "string (date-time)",
      "manager": "string",
      "serialnumberFilter": "string",
      "versionName": "string"
    }
  ]
}

Manager

Append a version assignment

POST /product/{product}/currentVersionAssignment

CurrentVersionAssignment

Version assignment

product: string

in path

Product Name

Request Content-Types: application/json

Request Example

{
  "currentVersionAssignment": {
    "serialnumberFilter": "string",
    "versionName": "string"
  }
}

200 OK

Success

New assignment accepted

400 Bad Request

Error

New assignment rejected

Response Example (200 OK)

{
  "code": "integer"
}

Response Example (400 Bad Request)

{
  "code": "integer",
  "error": "string"
}

Manager

Insert a version assignment before the given assignment

POST /product/{product}/currentVersionAssignment/{id}

CurrentVersionAssignment

Version assignment

product: string

in path

Product Name

id: string

in path

Existing assignment ID

Request Content-Types: application/json

Request Example

{
  "currentVersionAssignment": {
    "serialnumberFilter": "string",
    "versionName": "string"
  }
}

200 OK

Success

New assignment accepted

400 Bad Request

Error

Invalid assignment

404 Not Found

Error

Unknown assignment

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer"
}

Response Example (400 Bad Request)

{
  "code": "integer",
  "error": "string"
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Manager

Remove the given assignment

DELETE /product/{product}/currentVersionAssignment/{id}

product: string

in path

Product Name

id: string

in path

Assignment ID

200 OK

Success

Assignment removed

404 Not Found

Error

Unknown assignment

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer"
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Manager

Modify the given assignment

PATCH /product/{product}/currentVersionAssignment/{id}

CurrentVersionAssignment

Version assignment

product: string

in path

Product Name

id: string

in path

Assignment ID

Request Content-Types: application/json

Request Example

{
  "currentVersionAssignment": {
    "serialnumberFilter": "string",
    "versionName": "string"
  }
}

200 OK

Success

New assignment accepted

400 Bad Request

Error

Invalid assignment

404 Not Found

Error

Unknown assignment

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer"
}

Response Example (400 Bad Request)

{
  "code": "integer",
  "error": "string"
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Manager Maintainer

Get a list of all existing versions for a product

GET /product/{product}/version

product: string

in path

Product Name

200 OK

VersionList

Maintainer

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "versions": [
    {
      "date": "string (date-time)",
      "name": "string",
      "maintainer": "string",
      "available": "boolean"
    }
  ]
}

Manager Maintainer

Get information about a version

GET /product/{product}/version/{version}

product: string

in path

Product Name

version: string

in path

Version Name

200 OK

VersionInfo

Version

404 Not Found

Error

Version not found

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "version": {
    "date": "string (date-time)",
    "name": "string",
    "maintainer": "string",
    "available": "boolean"
  }
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Manager

Mark the version as available or unavailable

PATCH /product/{product}/version/{version}

VersionEdit

undefined

product: string

in path

Product Name

version: string

in path

Version Name

Request Content-Types: application/json

Request Example

{
  "version": {
    "available": "boolean"
  }
}

200 OK

Success

The version has been marked acordingly

404 Not Found

Error

Version not found

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer"
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Maintainer Manager Devices

Download the version's manifest

GET /product/{product}/version/{version}/manifest

product: string

in path

Product Name

version: string

in path

Version Name

200 OK

The version's mainfest file

404 Not Found

Version not found

Response Content-Types: application/cms

Response Headers (200 OK)


X-Upload-Date	Upload date as Unix timestamp	integer

Devices

Devices Maintainer Manager

Download an existing BLOB

GET /blob/{sha256}/data

sha256: string

in path

SHA256 of the BLOB

200 OK

Data

404 Not Found

Blob does not exist

Response Content-Types: application/octet-stream

Maintainer Devices Manager

Get the delta between a known BLOB and a desired BLOB

GET /blob/{sha256}/xdeltadiff/{knownfilesha256}

sha256: string

in path

SHA256 of the desired BLOB

knownfilesha256: string

in path

SHA256 of the known BLOB

200 OK

The xdelta3 diff to the given hash

404 Not Found

Blob does not exist

428 Precondition Required

Blob with the given knownfilesha256 does not exist

Response Content-Types: application/octet-stream

Devices Manager

Get the current version

GET /product/{product}/currentVersion

product: string

in path

Product Name

serialnumber: string

in query

Managers must state a serialnumber get the right version info. For devices this parameter is ignored and the common name of the device's certificate is used instead.

installedVersion: string

in query

Give information about the currently installed version. This will be written to the SDU server's log.

200 OK

CurrentVersion

Current version assignment

404 Not Found

Error

No assignment available for this product or serialnumber

Response Content-Types: application/json

Response Example (200 OK)

{
  "code": "integer",
  "currentVersion": {
    "date": "string (date-time)",
    "manager": "string",
    "name": "string"
  }
}

Response Example (404 Not Found)

{
  "code": "integer",
  "error": "string"
}

Maintainer Manager Devices

Download the version's manifest

GET /product/{product}/version/{version}/manifest

product: string

in path

Product Name

version: string

in path

Version Name

200 OK

The version's mainfest file

404 Not Found

Version not found

Response Content-Types: application/cms

Response Headers (200 OK)


X-Upload-Date	Upload date as Unix timestamp	integer

Schema Definitions

Error: object

code: integer: Error number for machines
error: string: Human-readable error describing the problem

Example

{
  "code": "integer",
  "error": "string"
}

Success: object

code: integer: Always zero

Example

{
  "code": "integer"
}

Blob: object

sha256: string: The content's SHA256
date: string (date-time): Update date of this definition
size: integer: Size of the BLOB in bytes
maintainer: string: Maintainer who uploaded this BLOB
referencedByVersion: boolean: Indicates whether this BLOB is used by any uploaded version

Example

{
  "sha256": "string",
  "date": "string (date-time)",
  "size": "integer",
  "maintainer": "string",
  "referencedByVersion": "boolean"
}

BlobList: object

code: integer: Always zero
blobs: Blob
Blob

Example

{
  "code": "integer",
  "blobs": [
    {
      "sha256": "string",
      "date": "string (date-time)",
      "size": "integer",
      "maintainer": "string",
      "referencedByVersion": "boolean"
    }
  ]
}

BlobInfo: object

code: integer: Always zero
blob: Blob

Example

{
  "code": "integer",
  "blob": {
    "sha256": "string",
    "date": "string (date-time)",
    "size": "integer",
    "maintainer": "string",
    "referencedByVersion": "boolean"
  }
}

ProductList: object

code: integer: Always zero
products: string[]
string

Example

{
  "code": "integer",
  "products": [
    "string"
  ]
}

Version: object

date: string (date-time): Upload date of this version
name: string: Version name
maintainer: string: The maintainer who signed this version
available: boolean: Is this version downloadable by devices?

Example

{
  "date": "string (date-time)",
  "name": "string",
  "maintainer": "string",
  "available": "boolean"
}

VersionInfo: object

code: integer: Always zero
version: Version

Example

{
  "code": "integer",
  "version": {
    "date": "string (date-time)",
    "name": "string",
    "maintainer": "string",
    "available": "boolean"
  }
}

VersionList: object

code: integer: Always zero
versions: Version
Version

Example

{
  "code": "integer",
  "versions": [
    {
      "date": "string (date-time)",
      "name": "string",
      "maintainer": "string",
      "available": "boolean"
    }
  ]
}

VersionEdit: object

version: object
available: boolean Is this version downloadable by devices?

Example

{
  "version": {
    "available": "boolean"
  }
}

CurrentVersion: object

code: integer: Always zero
currentVersion: object
date: string (date-time) Update date of this definition manager: string Manager who stored this definition name: string Version to install

Example

{
  "code": "integer",
  "currentVersion": {
    "date": "string (date-time)",
    "manager": "string",
    "name": "string"
  }
}

CurrentVersionAssignmentList: object

code: integer: Always zero
currentVersionAssignments: object[]
object id: string A random identifier for this assignment date: string (date-time) Update date of this definition manager: string Manager who stored this definition serialnumberFilter: string Regular expression for matching serial numbers versionName: string Version string

Example

{
  "code": "integer",
  "currentVersionAssignments": [
    {
      "id": "string",
      "date": "string (date-time)",
      "manager": "string",
      "serialnumberFilter": "string",
      "versionName": "string"
    }
  ]
}

CurrentVersionAssignment: object

currentVersionAssignment: object
serialnumberFilter: string Regular expression for matching serial numbers versionName: string Version string

Example

{
  "currentVersionAssignment": {
    "serialnumberFilter": "string",
    "versionName": "string"
  }
}

Documentation by Spectacle