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 'waitTimeout'. 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
- waitTimeout: (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. - commandRetentionTtl: (integer - default: 720)
The time (in hours) 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 'waitTimeout' or 'commandRetentionTtl' 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.
/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: (integer)
Http status code.
- reasonPhrase: (string)
Status code description.
- requestPayload: (any)
Request payload to endpoint.
- responsePayload: (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: (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.