Here is new documentation version.
You are reading outdated documentation, which will be shutdown soon!

REST API

Command Invocation 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)

Commands

Command opreations.

/endpoints/{endpointId}/commands/{commandType} post

post /endpoints/{endpointId}/commands/{commandType}

Invokes command on an endpoint. Returns command execution result if the command was executed within the specified 'waitTimeout'. Otherwise, returns the command result resource URL in the 'Location' header.

Secured by oauth_2_0 with scopes:
  • endpoint:update

CEX supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • endpointId: required(string)

    Unique endpoint identifier.

  • commandType: required(string)

    Represents the command type that a client wants to invoke on an endpoint. Command type MUST be a non-empty alpha-numeric string identifying the command type to the endpoint.

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

Query Parameters

  • waitTimeout: optional (integer - default: 5)

    The maximum duration (in seconds) a web client is willing to wait for a command execution response from a device. Must not be greater than specified spring.mvc.async.request-timeout value (60 seconds by default). See Spring documentation for the details.

  • commandRetentionTtl: optional (integer - default: 720)

    The time (in hours) that the command invocation will be eligible for the execution by an endpoint.

Body

Media type: application/json

Type: any

Example:

{
  "longitude": 1.23463453,
  "latitude": 0.92312412
}

HTTP status code 200

Command was successfully invoked.

Body

Media type: application/json

Type: any

Example:

{
  "message": "Client custom response"
}

HTTP status code 202

Command was accepted for the execution. Returns 'Location' header for fetching the command execution result.

Headers

  • Location: required(string)

    Location of the newly created command for retrieving a result.

HTTP status code 400

Invalid 'waitTimeout' or 'commandRetentionTtl' parameter value.

HTTP status code 404

Endpoint is not found or the querying user is denied access.

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.

/endpoints/{endpointId}/commands/{commandType}/{commandId} get

get /endpoints/{endpointId}/commands/{commandType}/{commandId}

Returns command information.

Secured by oauth_2_0 with scopes:
  • endpoint:read

CEX supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • endpointId: required(string)

    Unique endpoint identifier.

  • commandType: required(string)

    Represents the command type that a client wants to invoke on an endpoint. Command type MUST be a non-empty alpha-numeric string identifying the command type to the endpoint.

  • commandId: required(integer)

    Unique command identifier.

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

HTTP status code 200

Information is successfully retrieved.

Body

Media type: application/json

Type: object

Properties

  • commandId: required(integer)

    Command unique identifier.

  • commandType: required(string)

    Command type.

  • endpointId: required(string)

    Endpoint unique identifier.

  • status: required(string)

    Status of command execution

  • statusCode: optional (integer)

    Http status code.

  • reasonPhrase: optional (string)

    Status code description.

  • requestPayload: optional (any)

    Request payload to endpoint.

  • responsePayload: optional (any)

    Endpoint payload response.

Example:

{
  "commandId": 123,
  "commandType": "RESET",
  "endpointId": "123-id",
  "status": "executed",
  "statusCode": 200,
  "reasonPhrase": "Done successfully",
  "requestPayload": {
    "anyFields": "anyValues"
  },
  "responsePayload": {
    "anyFields": "anyValues"
  }
}

HTTP status code 404

Endpoint or resource with specified commandId is not found or the querying user is denied access.

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.