Essential Endpoints

Some endpoints are used in almost all scripted tasks. Below is a breakdown of those common endpoints including details about their return data format and supported features such as pagination and filtering.

Essential endpoints – users and organizations

/rest/v3/users

The Users endpoint is used to get, create and update User accounts in your Commander system. This endpoint is used regularly as many scripts and automated processes require you to look up a user or modify a user as part of the workflow.

To retrieve a User there are two options:

retrieve the user directly
retrieve a list and filter for the user you want.

To retrieve a User directly, make the following call substituting {user_name} for the user’s Commander username:

GET https://vCommander.embotics.com/rest/v3/users/{user_name}

The API will respond with a single User entity:

{
	"id": 1,
	"name": "superuser",
	"type": "LOCAL",
	"first_name": null,
	"last_name": null,
	"email": "SUPERUSER@EMBOTICS.COM",
	"primary_phone": null,
	"alternate_phone": null,
	"role": "SUPERUSER",
	"is_enabled": true,
	"links": [{
			"rel": "self",
			"href": "https://vCommander.embotics.com/rest/v3/users/superuser",
			"method": "GET" 
		}
	]
}

Notice that the name and phone fields are null. This is because the user is a LOCAL user type and the name and phone fields are often not populated. If this were an AD/LDAP user, then these fields would likely be populated from the AD/LDAP server. Additionally, an AD/LDAP user would have a list that describes the AD Groups that the user is a part of:

"active_directory_groups":
[
 	"GROUPS"
]

The second option for finding a User is to retrieve the User collection and filter it using the Filters feature of the Commander API.

The example below shows how to apply a filter to retrieve users with a specific role:

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

The API will then reply with a collection of user entities that matches the filter:

{
	"pagination": {
		"page_size": 100,
		"page_number": 1
	},
	"items": [{			
			"id": 4,
			"name": "manager",
			"links": [{
					"rel": "self",
					"href": "https://vCommander.embotics.com/rest/v3/users/manager",
					"method": "GET "
				}
			]
		}, {
			"id": 1,
			"name": "portal-manager",
			"links": [{
					"rel": "self",
					"href": "https://vCommander.embotics.com/rest/v3/users/portal-manager",
					"method": "GET"
				}
			]
		}
	]
}

For the collection of User items, the unique identifier is the “name” field, so the name is included in each of the results in the collection. The links include the reference to the full User resource as in the GET rest/v3/users/{username} example above.

Organizations

/rest/v3/organizations

The Organizations endpoint is used to get, create and update Organizations in your Commander system. This endpoint is used regularly as many scripts and automated processes require you to look up an Organization or modify the membership of an Organization as part of the workflow.

To retrieve an Organization there are two options:

retrieve the Organization directly
retrieve a list and filter for the Organization you want.

To retrieve an Organization directly make the following call substituting {org_name} for the Organizations name:

GET https://vCommander.embotics.com/rest/v3/organizations/{org_name}

The API will respond with a single Organization entity:

{
	"id": 40,
	"name": "org-name",
	"resource_quota": null,
	"cost_quota": null,
	"links": [{
			"rel": "self",
			"href": "https://vCommander.embotics.com/rest/v3/organizations/org-name",
			"method": "GET" 
		}
	]
}

Note that the Organization entity returned shows only the Name, ID and Quota information for the Organization. To get the Membership details for the Organization you must call the Organization Members endpoint:

GET https://vCommander.embotics.com/rest/v3/organizations/{org_name}/members

This will return a paginated list of the members of the selected Organization:

{
	"pagination": {
		"page_size": 100,
		"page_number": 1
	},
	"items": [{
			"name": "org-user-1",
			"id": 50,
			"link": {
				"rel": "self",
				"href": "https://vCommander.embotics.com/rest/v3/organizations/org-name/members/org-user-1",
				"method": "GET"
			}
		}, {
			"name": "org-user-2",
			"id": 10061,
			"link": {
				"rel": "self",
				"href": "https://vCommander.embotics.com/rest/v3/organizations/org-name/members/org-user-2",
				"method": "GET"
			}
		}
	]
}

For the collection of Member items, the unique identifiers are the “name” and “id” fields so those two included. The links include the reference to the full Member resource if additional detail is needed.

Essential endpoints – service definitions and service requests

Service definitions

/rest/v3/services

The Services endpoint is used to retrieve the catalog of Service Definitions, which can then be used to perform a Service Request to deploy VMs or other resources.

To retrieve a Service Definition to allow you to request a Service you first perform this call to get the Service Definition:

GET https://vCommander.embotics.com/rest/v3/services

The Commander API will return a collection of Services:

{
	"pagination": {
		"page_size": 100,
		"page_number": 1
	},
	"items": [{
			"id": 13,
			"name": "BASIC LINUX",
			"type": "SERVICE",
			"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" 
				}
			]
		}, {
			"id": 26,
			"name": "WINDOWS DEVELOPMENT BOX",
			"type": "SERVICE",
			"links": [ {
					"rel": "request-form",
					"href": "https://vCommander.embotics.com/rest/v3/services/26/request-form",
					"method": "GET"
				}, {
					"rel": "service-requests",
					"href": "https://vCommander.embotics.com/rest/v3/service-requests",
					"method": "POST"
				}
			]
		}
	]
}

When making the request you can also pass in a Filter and Pagination parameters as with other GET requests.

Valid filters include the Name, Categories, and Id fields. Using a Name or Id with an equals operator will return a single result in the items list in the reply.

Service requests

/rest/v3/service-requests

The Service Requests endpoints allow you to submit a Service Request and get a past Request to view the status.

You can get either a list of Requests or a specific request by ID. To get a previously submitted Service Request by ID, make the following call:

GET https://vCommander.embotics.com/rest/v3/service-requests/{id}

The call will return the requested Service Request which can be very lengthy. A truncated example is below:

{
	"summary": {
		"id": 56,
		"request_type": "NEW_REQUEST",
		"state": "PENDING_APPROVAL",
		"date_submitted": "2018-06-22T18:45:21Z",
		"date_completed": null,

		…
		"resource_summary": { … },
		"cost_summary": { … }
	},
	"services": [{	
		"service": {
			"name": "BASIC WINDOWS SERVER",
			"summary": { … },
			"configuration": { … }
		},
		"components": [{
			"name": "SERVER2008R2",
			"summary": { … },
			"configuration": {
				"memory": { … },
				"cpu_count": 1,
				"network": [{ … }],
				"disks": [{ … }],
						…
			}
		}]
	}],
	"links": [{ … }]
}

To retrieve a list of Service Requests you would make the following call:

GET https://vCommander.embotics.com/rest/v3/service-requests

As with all collections, the response includes pagination details and supports filters. Specifically, you can filter using the state, submitted_by, and deployed_name fields.