API Conventions

Supported HTTP verbs, errors and expected responses

The Commander API supports the following HTTP verbs:

  • PUT
  • POST
  • GET

When performing these actions certain responses are guaranteed, specifically:




On success, return HTTP Code 201 and the details of the created resource (i.e. the same object that would be returned for getting the details of the resource)


On success, return HTTP Code 200 and the details of the updated resource (i.e. the same object that would be returned for getting the details of the resource)


On success, return HTTP Code 204; doesn't include the deleted resource in the response

A range of HTTP Error Codes are also supported to help identify the type of error that occurred:




The generic success response.

Returned for a successful GET operation on a collection of resources e.g. GET /users

Returned for a successful GET operation for the details of an individual resource e.g. GET /users/jim

Returned for a successful update to a resource e.g. PATCH /users/jim


A success response that indicates a resource was created

Returned for POST operations that create a new resource e.g. POST /users


A success response that indicates the request was accepted and will be processed asynchronously

Returned for POST operations that create a new resource asynchronously e.g. POST /users in scenario where synchronous request has timed out


A success response that indicates there is no response body

Returned for DELETE operation e.g. DELETE /users/jim


Generic client side error


Client side error

Returned for invalid credentials


Client side error

Returned for authorization errors


Client side error

Returned when requested resource doesn't exist


Error code used for rate limiting a client


Generic server side error

Supported primitive data types

The Commander API supports the following primitive Data Types:




An ASCII text string


A number including integer numbers (1,2,3, -12, 0) and decimal values (12.45)


A UTC (ISO 8601) formatted datetime (yyyy-MM-ddTHH:mm:ssZ)


true/false values are accepted


Enum names are always in capital letter with underscores to separate words (PENDING_APPROVAL)

API URL format

The Commander API endpoints are accessed using the following URL format:


You can use either the IP address of the Commander server or the Hostname of the machine Commander is installed on. API resources are all accessed using HTTPS.

Endpoints for individual resources, such as a single User account, are accessed using a unique property. For example, individual Users are accessed using their username:


Some resources are accessed using a name type property, such as Users, and some are accessed using an ID value, such as Service Requests:


Endpoints for collections of resources are plural. For example, the collection of User resources is accessed at the plural “Users” endpoint as seen above.

For endpoints which contain multiple words the words are separated using a hyphen character. For example, the endpoint to access the Service Requests resources is:


Filtering API call results

Many of the endpoints in the Commander API support filtering features which let you receive a limited set of resources from the API that match a set of filters. The example below is for the Users resource endpoint, which demonstrates filtering:

Example – Filtering User Accounts by Role

https://vCommander.embotics.com/rest/v3/users?filter=role -eq MANAGER

This will return all Users which have the ‘manager’ role.

The filter system supports a variety of comparison operators as well as a set of logical operators. The filter system is very powerful and allows you to specify complex queries as part of your request to the API. The table below details which operators are available and which data types those operators work on:

Operator Name


Applies To



String, Number, Enum, Boolean, Date

Not Equal


String, Number, Enum, Boolean, Date

Greater Than


Number, Date

Greater or Equal


Number, Date

Less Than


Number, Date

Less or Equal


Number, Date



String, Collection

Does Not Contain


String, Collection











( )


There are several special characters in the filtering grammar that require special handling: single quote, double quote, dash, parentheses, backslash, space and comma. When these characters are used in strings, the following rules apply:

String Type




single quoted string



filter=name -contains '\''



filter=name -contains '\\'

double quoted string



filter=name -contains "\""



filter=name -contains "\\"

unquoted string


cannot start with

filter=name -contains 8abc


cannot start with

filter=name -contains -abc


cannot contain

filter=name -contains a(bc


cannot contain

filter=name -contains a)bc


cannot contain

filter=name -contains a'bc


cannot contain

filter=name -contains a"bc


cannot contain

filter=name -contains a,bc


cannot contain

filter =name -contains a bc

Parentheses group the left-value, the operator, and the right-value into an operand of the filter. They are always required, except for the most basic expressions consisting of a single operator. Below is an example of an expression with a single operator, which doesn't require parentheses.

GET https://vCommander.embotics.com/rest/v3/users?filter=role -eq MANAGER

For more complex expressions consisting of multiple operators, or even a single -not operator, parentheses are required:

GET https://vCommander.embotics.com/rest/v3/users?filter=(role -eq MANAGER) -and (is_enabled -eq false)
GET https://vCommander.embotics.com/rest/v3/services?filter=-not(name -contains AWS)

The logical operators can be used to chain together filters. Each element of the chain must be encapsulated in parentheses. For example, to get all services where the service name contains "AWS" and the service belongs to either the "Linux" or "Windows" categories, the call would be:

GET https://vCommander.embotics.com/rest/v3/services?filter=(name -contains AWS) -and ((categories -contains Windows) -or (categories -contains Linux))


Some endpoints, such as the Users or Organizations endpoints, return collections of entities. These responses will be paginated for transmission efficiency and you may need to make multiple requests to retrieve the full set of those entities.

The JSON response for paginated collections will include a “pagination” entity in the response body. An example of that entity is below:

"pagination": {
		"page_size": 100,
		"page_number": 1

This entity will tell you the current maximum number of items in the response (the page_size) and the current page in the collection being viewed (page_number).

The default page size and page number are 100 and 1, respectively. When you make requests to endpoints that return collections you can specify a different page size and page number which allows you to iterate the full set of entities in the collection.

For example, to get the first 50 Users you would perform the following call:

GET https://vCommander.embotics.com/rest/v3/users?page_size=50&page_number=1

This would return a collection of the first 50 Users. To then get the next 50 Users you would make the following call:

GET https://vCommander.embotics.com/rest/v3/users?page_size=50&page_number=2

You continue this process until the call returns an empty collection at which point you have reached the end of the set. An example of the empty collection response is below:

	"pagination": {
		"page_size": 50,
		"page_number": 23
	"items": []

When the “Items” collection element is empty you know you have iterated the whole set.


When you get a collection of resources, such as a list of Users, the items returned are sparse and contain only the unique identifier fields, such as Name and Id, and the Links section.

This minimizes the data that must be returned and allows you to easily access the individual items in future API calls if needed. If a collection is empty, it's included in the structure as empty array (that is, [ ]); a collection is never null or missing from the return body.

The Commander API provides HATEOS links in the response to most API calls. An example is displayed below:

	"pagination": {
		"page_size": 100,
		"page_number": 1
	"items": [{
			"id": 13,
			"name": "BASIC LINUX",
			"links": [{
					"rel": "request-form",
					"href": "https://vCommander.embotics.com/rest/V3/services/13/request-form",
					"method": "GET"
				}, {
					"rel": "service-requests",
					"href": "https://vCommander.embotics.com/rest/v3/service-requests",
					"method": "POST"

This example shows the result of performing a GET on the /Services endpoint. The Service returned in the Items collection contains a Links section which includes references to additional details related to that Service. Specifically, it includes links to the Service details, the Service Request Form and the Service Requests for this Service.

This Links section appears in most endpoints where an entity, such as a Service, is returned and facilitates easy navigation through the data model through the API.