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

Get a list of present BLOBs

GET /blob
200 OK

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"
    }
  ]
}

Get info about existing BLOB

GET /blob/{sha256}
sha256: string
in path

SHA256 of the BLOB

200 OK

Version

404 Not Found

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"
}

Upload a new BLOB

POST /blob/{sha256}
sha256: string
in path

SHA256 of the content

200 OK

The data has been accepted

400 Bad Request

SHA256 mismatch

409 Conflict

Blob already existing

413 Request Entity Too Large

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"
}

Delete an existing BLOB

DELETE /blob/{sha256}
sha256: string
in path

SHA256 of the content

200 OK

The blob has been delete

400 Bad Request

Blob is referenced by a version

404 Not Found

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"
}

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

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

Get a list of all products

GET /product
200 OK

Current version assignment

Response Content-Types: application/json
Response Example (200 OK)
{
  "code": "integer",
  "products": [
    "string"
  ]
}

Get a list of all existing versions for a product

GET /product/{product}/version
product: string
in path

Product Name

200 OK

Maintainer

Response Content-Types: application/json
Response Example (200 OK)
{
  "code": "integer",
  "versions": [
    {
      "date": "string (date-time)",
      "name": "string",
      "maintainer": "string",
      "available": "boolean"
    }
  ]
}

Get information about a version

GET /product/{product}/version/{version}
product: string
in path

Product Name

version: string
in path

Version Name

200 OK

Version

404 Not Found

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"
}

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

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

The version already exists or the manifest is invalid

Response Example (400 Bad Request)
{
  "code": "integer",
  "error": "string"
}

Manager

Get a list of present BLOBs

GET /blob
200 OK

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"
    }
  ]
}

Get info about existing BLOB

GET /blob/{sha256}
sha256: string
in path

SHA256 of the BLOB

200 OK

Version

404 Not Found

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"
}

Delete an existing BLOB

DELETE /blob/{sha256}
sha256: string
in path

SHA256 of the content

200 OK

The blob has been delete

400 Bad Request

Blob is referenced by a version

404 Not Found

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"
}

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

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

Get a list of all products

GET /product
200 OK

Current version assignment

Response Content-Types: application/json
Response Example (200 OK)
{
  "code": "integer",
  "products": [
    "string"
  ]
}

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.

Current version assignment

404 Not Found

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"
}

Get the current version assignment

GET /product/{product}/currentVersionAssignment
product: string
in path

Product Name

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"
    }
  ]
}

Append a version assignment

POST /product/{product}/currentVersionAssignment

Version assignment

product: string
in path

Product Name

Request Content-Types: application/json
Request Example
{
  "currentVersionAssignment": {
    "serialnumberFilter": "string",
    "versionName": "string"
  }
}
200 OK

New assignment accepted

400 Bad Request

New assignment rejected

Response Example (200 OK)
{
  "code": "integer"
}
Response Example (400 Bad Request)
{
  "code": "integer",
  "error": "string"
}

Insert a version assignment before the given assignment

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

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

New assignment accepted

400 Bad Request

Invalid assignment

404 Not Found

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"
}

Remove the given assignment

DELETE /product/{product}/currentVersionAssignment/{id}
product: string
in path

Product Name

id: string
in path

Assignment ID

200 OK

Assignment removed

404 Not Found

Unknown assignment

Response Content-Types: application/json
Response Example (200 OK)
{
  "code": "integer"
}
Response Example (404 Not Found)
{
  "code": "integer",
  "error": "string"
}

Modify the given assignment

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

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

New assignment accepted

400 Bad Request

Invalid assignment

404 Not Found

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"
}

Get a list of all existing versions for a product

GET /product/{product}/version
product: string
in path

Product Name

200 OK

Maintainer

Response Content-Types: application/json
Response Example (200 OK)
{
  "code": "integer",
  "versions": [
    {
      "date": "string (date-time)",
      "name": "string",
      "maintainer": "string",
      "available": "boolean"
    }
  ]
}

Get information about a version

GET /product/{product}/version/{version}
product: string
in path

Product Name

version: string
in path

Version Name

200 OK

Version

404 Not Found

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"
}

Mark the version as available or unavailable

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

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

The version has been marked acordingly

404 Not Found

Version not found

Response Content-Types: application/json
Response Example (200 OK)
{
  "code": "integer"
}
Response Example (404 Not Found)
{
  "code": "integer",
  "error": "string"
}

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

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

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

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.

Current version assignment

404 Not Found

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"
}

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"
  }
}