API Conventions

Supported HTTP verbs, errors and expected responses

The Commander API supports the following HTTP verbs:

• PUT
• POST
• PATCH
• GET
• DELETE

When performing these actions certain responses are guaranteed, specifically:

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

Supported primitive data types

The Commander API supports the following primitive Data Types:

API URL format

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

https://<vCommander-IP-or-Hostname>/rest/v3/<endpoint>

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:

https://<vCommander-IP-or-Hostname>/rest/v3/users/jsmith

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

https://<vCommander-IP-or-Hostname>/rest/v3/service-requests/8695

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:

https://<vCommander-IP-or-Hostname>/rest/v3/service-requests/

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:

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:

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))

Pagination

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.

Collections

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.

HATEOAS links

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.