Command Invocation REST 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.

post
post

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.

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: (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: (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 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: (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.

get delete
get

Returns command information.

delete

Deletes command.

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: (integer)

    Http status code.

  • reasonPhrase: (string)

    Status code description.

  • requestPayload: (any)

    Request payload to endpoint.

  • responsePayload: (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: (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.

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: (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.

get
get

Returns last executed command by endpoint.

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: (integer)

    Http status code.

  • reasonPhrase: (string)

    Status code description.

  • requestPayload: (any)

    Request payload to endpoint.

  • responsePayload: (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: (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.

get
get

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

get
get

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

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 cex-api-types.CommandDescriptorsForEndpoint)

    Items: CommandDescriptorsForEndpoint

    • endpointId: required(string)

      Unique endpoint identifier.

    • commands: required(array of cex-api-types.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: (integer)

        Http status code.

      • reasonPhrase: (string)

        Status code description.

      • requestPayload: (any)

        Request payload to endpoint.

      • responsePayload: (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: (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.

post
post

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

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: (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: (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.

post
post

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

Invokes command on specified endpoints. 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}

Query Parameters

  • commandTtl: (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: object

Properties
  • payload: required(string)

    Command payload

  • payloadContentType: required(string)

    Command payload content type. 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.

  • endpointIds: required(string)

    Endpoint IDs

Example:

{
  "payload": "{\"state\": \"ON\"}",
  "payloadContentType": "application/json",
  "endpointIds": [
    "56726466-e454-23ac-340c-f34fefda7d01"
  ]
}

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: (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.

get
get

Returns the history of batch command execution tasks.

get
get

Returns batch command execution task status.

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 cex-api-types.BatchCommandExecutionItem)

    Array of commands that has 'pending' state.

    Items: BatchCommandExecutionItem

    • endpointId: (string)

      Endpoint ID.

    • commandId: required(integer)

      Command ID.

  • executed: required(array of cex-api-types.BatchCommandExecutionItem)

    Array of commands that has 'executed' state.

    Items: BatchCommandExecutionItem

    • endpointId: (string)

      Endpoint ID.

    • commandId: required(integer)

      Command ID.

  • expired: required(array of cex-api-types.BatchCommandExecutionItem)

    Array of commands that has 'expired' state.

    Items: BatchCommandExecutionItem

    • endpointId: (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: (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.