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 'awaitTimeout'. 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

  • awaitTimeout: 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.

  • commandTtl: optional (integer - default: 60000)

    The time (in milliseconds) 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 'awaitTimeout' or 'commandTtl' 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 delete

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.

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

Deletes command.

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.

  • 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 204

Command is successfully deleted.

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.

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

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

Returns last sent command.

Secured by oauth_2_0 with scopes:
  • endpoint:read

CEX supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • endpointId: required(string)
  • commandType: required(string)

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

Query Parameters

  • endpointId: required(string)

    Endpoint ID

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f
  • commandType: required(string)

    Example:

    start

HTTP status code 200

The last command that was sent to the endpoint and has executed status 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

Last command that has executed status not found.

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/commands get

get /endpoints/commands

Returns a list of all commands for given endpoints grouped by endpoint.

Secured by oauth_2_0 with scopes:
  • endpoint:read

CEX supports OAuth 2.0 for authenticating all API requests.

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

Query Parameters

  • endpointId: required(array of string)

    Comma-separated list of endpoint IDs

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f,8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297

HTTP status code 200

List of endpoints commands grouped by endpoint is successfully retrieved.

Body

Media type: application/json

Type: array of CommandDescriptorsForEndpoint

Items: CommandDescriptorsForEndpoint

  • endpointId: required(string)

    Unique endpoint identifier.

  • commands: required(array of CommandDescriptor)

    List of commands

    Items: CommandDescriptor

    • 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:

[
  {
    "endpointId": "ep1",
    "commands": [
      {
        "commandId": 123,
        "commandType": "RESET",
        "endpointId": "123-id",
        "status": "executed",
        "statusCode": 200,
        "reasonPhrase": "Done successfully",
        "requestPayload": {
          "anyFields": "anyValues"
        },
        "responsePayload": {
          "anyFields": "anyValues"
        }
      },
      {
        "commandId": 321,
        "commandType": "RESET",
        "endpointId": "123-id",
        "status": "pending",
        "statusCode": 200,
        "reasonPhrase": "Done successfully",
        "requestPayload": {
          "anyFields": "anyValues"
        }
      }
    ]
  }
]

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/commands/{applicationName} get

get /endpoints/commands/{applicationName}

Returns a pagable list of all commands for given endpoints in specific application.

Secured by oauth_2_0 with scopes:
  • application:endpoint-command:read

CEX supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • applicationName: required(string)

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

HTTP status code 200

Pageble list of endpoints commands is successfully retrieved.

Body

Media type: application/json

Type: object

Properties

  • content: required(array of CommandDescriptorsForEndpoint)

    Items: CommandDescriptorsForEndpoint

    • endpointId: required(string)

      Unique endpoint identifier.

    • commands: required(array of CommandDescriptor)

      List of commands

      Items: CommandDescriptor

      • 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.

  • pageable: required(object)
    • sort: required(object)
      • sorted: required(boolean)
      • unsorted: required(boolean)
      • empty: required(boolean)
    • pageNumber: required(integer)
    • pageSize: required(integer)
    • offset: required(integer)
    • paged: required(boolean)
    • unpaged: required(boolean)
  • totalElements: required(integer)
  • totalPages: required(integer)
  • last: required(boolean)
  • sort: required(object)
    • sorted: required(boolean)
    • unsorted: required(boolean)
    • empty: required(boolean)
  • numberOfElements: required(integer)
  • first: required(boolean)
  • size: required(integer)
  • number: required(integer)
  • empty: required(boolean)

Example:

{
  "content": [
    {
      "createdAt": {
        "nano": 713000000,
        "epochSecond": 1576763997
      },
      "updatedAt": {
        "nano": 713000000,
        "epochSecond": 1576763997
      },
      "commandId": 284,
      "commandType": "get-co2",
      "endpointId": "e11acaa6-d35e-463b-be92-b9b4a1245c44",
      "status": "PENDING",
      "statusCode": null,
      "reasonPhrase": null,
      "requestPayload": {
        "command": "MAX:1h"
      },
      "responsePayload": null
    },
    {
      "createdAt": {
        "nano": 185000000,
        "epochSecond": 1576760458
      },
      "updatedAt": {
        "nano": 185000000,
        "epochSecond": 1576760458
      },
      "commandId": 284,
      "commandType": "get-co2",
      "endpointId": "23e1f247-b7db-4d96-8f96-545ed7c20574",
      "status": "PENDING",
      "statusCode": null,
      "reasonPhrase": null,
      "requestPayload": {
        "command": "MAX:1h"
      },
      "responsePayload": null
    },
    {
      "createdAt": {
        "nano": 388000000,
        "epochSecond": 1576763437
      },
      "updatedAt": {
        "nano": 388000000,
        "epochSecond": 1576763437
      },
      "commandId": 284,
      "commandType": "get-co2",
      "endpointId": "8a93e4cf-fc7b-4160-a8b2-627b0d2ce9f4",
      "status": "PENDING",
      "statusCode": null,
      "reasonPhrase": null,
      "requestPayload": {
        "command": "MAX:1h"
      },
      "responsePayload": null
    }
  ],
  "pageable": {
    "sort": {
      "sorted": false,
      "unsorted": true,
      "empty": true
    },
    "pageNumber": 0,
    "pageSize": 20,
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalElements": 3,
  "totalPages": 1,
  "last": true,
  "sort": {
    "sorted": false,
    "unsorted": true,
    "empty": true
  },
  "numberOfElements": 3,
  "first": true,
  "size": 20,
  "number": 0,
  "empty": false
}

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.