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.
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.
- 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.
- 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.
- 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.
- commandId: required(integer)
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.
- 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.
- 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": {
"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.