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.
- 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.
get /endpoints/{endpointId}/commands/{commandType}/{commandId}
Returns command information.
- 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.
- 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.
- 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.
- 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.
- commandId: required(integer)
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.
- 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.
- commandId: required(integer)
- endpointId: required(string)
- 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)
- sort: required(object)
- 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.
- 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
- 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.
- 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.
- taskId: required(integer)
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.
- 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.
- endpointId: optional (string)
- executed: required(array of BatchCommandExecutionItem)
Array of commands that has 'executed' state.
Items: BatchCommandExecutionItem
- endpointId: optional (string)
Endpoint ID.
- commandId: required(integer)
Command ID.
- endpointId: optional (string)
- expired: required(array of BatchCommandExecutionItem)
Array of commands that has 'expired' state.
Items: BatchCommandExecutionItem
- endpointId: optional (string)
Endpoint ID.
- commandId: required(integer)
Command ID.
- endpointId: optional (string)
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.