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}
  • Content-Type: required(one of application/json, text/plain)

    Type of command payload.

    In case "application/json" is specified, the payload is validated to be a valid JSON.

    In case "text/plain" is specified, no specific validation logic is applied.

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.

  • createdAt: required(datetime)

    Timestamp in ISO 8601 format (UTC timezone) showing when the command was created.

  • updatedAt: required(datetime)

    Timestamp in ISO 8601 format (UTC timezone) showing when the command status was last updated.

Example:

{
  "commandId": 123,
  "commandType": "RESET",
  "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7705",
  "status": "EXECUTED",
  "statusCode": 200,
  "reasonPhrase": "Successfully executed",
  "requestPayload": {
    "anyFields": "anyValues"
  },
  "responsePayload": {
    "anyFields": "anyValues"
  },
  "createdAt": "2017-04-20T15:01:12.144Z",
  "updatedAt": "2017-04-20T15:01:25.286Z"
}

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 executed command by endpoint.

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.

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

HTTP status code 200

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

  • createdAt: required(datetime)

    Timestamp in ISO 8601 format (UTC timezone) showing when the command was created.

  • updatedAt: required(datetime)

    Timestamp in ISO 8601 format (UTC timezone) showing when the command status was last updated.

Example:

{
  "commandId": 123,
  "commandType": "RESET",
  "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7705",
  "status": "EXECUTED",
  "statusCode": 200,
  "reasonPhrase": "Successfully executed",
  "requestPayload": {
    "anyFields": "anyValues"
  },
  "responsePayload": {
    "anyFields": "anyValues"
  },
  "createdAt": "2017-04-20T15:01:12.144Z",
  "updatedAt": "2017-04-20T15:01:25.286Z"
}

HTTP status code 400

Invalid request.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 403

User does not have permissions to perform this operation.

HTTP status code 404

Last command that has the '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.

    • createdAt: required(datetime)

      Timestamp in ISO 8601 format (UTC timezone) showing when the command was created.

    • updatedAt: required(datetime)

      Timestamp in ISO 8601 format (UTC timezone) showing when the command status was last updated.

Example:

[
  {
    "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7705",
    "commands": [
      {
        "commandId": 123,
        "commandType": "RESET",
        "endpointId": "59126304-4970-4f80-91a1-06e9ae2b7705",
        "status": "EXECUTED",
        "statusCode": 200,
        "reasonPhrase": "Done successfully",
        "requestPayload": {
          "anyFields": "anyValues"
        },
        "responsePayload": {
          "anyFields": "anyValues"
        },
        "createdAt": "2017-04-20T15:01:12.144Z",
        "updatedAt": "2017-04-20T15:01:25.286Z"
      },
      {
        "commandId": 321,
        "commandType": "RESET",
        "endpointId": "aa773080-0fda-49c0-aacf-500baab0170b",
        "status": "PENDING",
        "requestPayload": {
          "anyFields": "anyValues"
        },
        "createdAt": "2017-04-20T15:01:12.244Z",
        "updatedAt": "2017-04-20T15:01:28.286Z"
      }
    ]
  }
]

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 pageable 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)

    Application name

    Example:

    smart-kettle

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

Query Parameters

  • page: required(integer)

    Page number started from zero.

  • size: required(integer)

HTTP status code 200

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

      • createdAt: required(datetime)

        Timestamp in ISO 8601 format (UTC timezone) showing when the command was created.

      • updatedAt: required(datetime)

        Timestamp in ISO 8601 format (UTC timezone) showing when the command status was last updated.

  • 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": "2017-04-20T15:01:12.144Z",
      "updatedAt": "2017-04-20T15:01:25.286Z",
      "commandId": 284,
      "commandType": "get-co2",
      "endpointId": "e11acaa6-d35e-463b-be92-b9b4a1245c44",
      "status": "PENDING",
      "statusCode": null,
      "reasonPhrase": null,
      "requestPayload": {
        "command": "MAX:1h"
      },
      "responsePayload": null
    },
    {
      "createdAt": "2017-04-20T15:01:12.144Z",
      "updatedAt": "2017-04-20T15:01:25.286Z",
      "commandId": 284,
      "commandType": "get-co2",
      "endpointId": "23e1f247-b7db-4d96-8f96-545ed7c20574",
      "status": "PENDING",
      "statusCode": null,
      "reasonPhrase": null,
      "requestPayload": {
        "command": "MAX:1h"
      },
      "responsePayload": null
    },
    {
      "createdAt": "2017-04-20T15:01:12.144Z",
      "updatedAt": "2017-04-20T15:01:25.286Z",
      "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.

/endpoints/commands/{commandType}/batch post

post /endpoints/commands/{commandType}/batch

Invokes command on the endpoints that match the specified filter ID. Returns the batch command execution task ID.

Secured by oauth_2_0 with scopes:
  • endpoint:update

CEX supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • commandType: required(string)

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

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}
  • Content-Type: required(one of application/json, text/plain)

    Type of command payload.

    In case "application/json" is specified, the payload is validated to be a valid JSON.

    In case "text/plain" is specified, no specific validation logic is applied.

Query Parameters

  • filterId: required(string)

    Unique filter identifier that endpoints must match.

  • commandTtl: optional (integer - default: 60000)

    The time (in milliseconds) that the command invocation will be eligible for the execution by endpoints.

Body

Media type: application/json

Type: any

Example:

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

HTTP status code 202

Batch command execution task is accepted.

Body

Media type: application/json

Type: object

Properties

  • taskId: required(integer)

    Batch command execution task ID.

Example:

{
  "taskId": 6591300
}

HTTP status code 400

Invalid request.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 403

User does not have permissions to perform this operation.

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/batch/tasks get

get /endpoints/commands/batch/tasks

Returns the history of batch command execution tasks.

Secured by oauth_2_0 with scopes:
  • application: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

  • appName: required(string)

    Application name.

    Example:

    smart-kettle
  • commandType: optional (string)

    Represents the command type that was invoked on the endpoints. Used as a filter.

    Example:

    powerOn
  • filterId: optional (string)

    Unique filter identifier that was used for batch command execution. Used as a filter.

    Example:

    452a38b5-452d-41a8-9651-bf304092faa3
  • sortBy: optional (one of commandType, createdAt, taskId)

    Represents the parameter that will be used for sorting results. Used together with sortOrder.

    Example:

    commandType
  • sortOrder: optional (one of ASC, DESC - default: ASC)

    Represents the sorting order parameter. Used together with sortBy.

    Example:

    DESC
  • offset: optional (integer)

    Start index that the server should return data from.

    Example:

    0
  • limit: optional (integer - default: 100)

    Maximum number of items to return. To get all items limit must be 0.

    Example:

    100

HTTP status code 200

The history of batch command execution tasks is successfully retrieved.

Body

Media type: application/json

Type: object

Properties

  • totalElements: required(integer)

    Total number of elements available for retrieval. Current response may return only a part of all available elements.

  • content: required(array of BatchCommandExecutionTaskStatus)

    Items: BatchCommandExecutionTaskStatus

    • taskId: required(integer)

      Task ID.

    • filterId: required(string)

      Filter ID.

    • commandType: required(string)

      Command type.

    • requestPayload: required(any)

      Request payload for commands.

    • createdAt: required(datetime)

      Timestamp in ISO 8601 format (UTC timezone) showing when the task was created.

    • pendingCount: required(integer)

      Count of commands that has 'pending' state.

    • executedCount: required(integer)

      Count of commands that has 'executed' state.

    • expiredCount: required(integer)

      Count of commands that were expired.

Example:

{
  "totalElements": 10,
  "content": [
    {
      "taskId": 15,
      "filterId": "330f1291-7791-46a0-bb6f-9128e0038d3b",
      "commandType": "power-switch",
      "requestPayload": {
        "state": "ON"
      },
      "createdAt": "2021-04-20T15:01:12.144Z",
      "pendingCount": 5,
      "executedCount": 8,
      "expiredCount": 1
    },
    {
      "taskId": 16,
      "filterId": "330f1291-7791-46a0-bb6f-9128e0038d3b",
      "commandType": "power-switch",
      "requestPayload": {
        "state": "OFF"
      },
      "createdAt": "2021-04-20T16:05:28.256Z",
      "pendingCount": 3,
      "executedCount": 10,
      "expiredCount": 1
    }
  ]
}

HTTP status code 400

Invalid request.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 403

User does not have permissions to perform this operation.

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/batch/tasks/{id} get

get /endpoints/commands/batch/tasks/{id}

Returns batch command execution task status.

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

CEX supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • id: required(integer)

    Batch command execution task ID.

    Example:

    6591300

Headers

  • Authorization: required(string)

    Used to send an OAuth 2.0 JWT.

    Example:

    Authorization: bearer {your-access-token}

Query Parameters

  • appName: required(string)

    Application name.

    Example:

    smart-kettle

HTTP status code 200

Batch command execution task's status is successfully retrieved.

Body

Media type: application/json

Type: object

Properties

  • pending: required(array of BatchCommandExecutionItem)

    Array of commands that has 'pending' state.

    Items: BatchCommandExecutionItem

    • endpointId: optional (string)

      Endpoint ID.

    • commandId: required(integer)

      Command ID.

  • executed: required(array of BatchCommandExecutionItem)

    Array of commands that has 'executed' state.

    Items: BatchCommandExecutionItem

    • endpointId: optional (string)

      Endpoint ID.

    • commandId: required(integer)

      Command ID.

  • expired: required(array of BatchCommandExecutionItem)

    Array of commands that has 'expired' state.

    Items: BatchCommandExecutionItem

    • endpointId: optional (string)

      Endpoint ID.

    • commandId: required(integer)

      Command ID.

Example:

{
  "pending": [
    {
      "endpointId": "56726466-e454-23ac-340c-f34fefda7d01",
      "commandId": 1
    }
  ],
  "executed": [
    {
      "endpointId": "56726466-e454-23ac-340c-f34fefda7d03",
      "commandId": 2
    }
  ],
  "expired": [
    {
      "endpointId": "56726466-e454-23ac-340c-f34fefda7d02",
      "commandId": 3
    }
  ]
}

HTTP status code 400

Invalid request.

Body

Media type: application/json

Type: object

Properties

  • message: required(string)

    Detailed error description.

HTTP status code 403

User does not have permissions to perform this operation.

HTTP status code 404

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