Here is
new documentation version.
You are reading outdated documentation, which will be shutdown soon!
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.
/endpoints/{endpointId}/commands/{commandType}/{commandId} get
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.
/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.