Common API Tasks

Along with the essential endpoints there are some tasks which are common to many automated processes that use the Commander API. Below are common tasks including examples of the calls and body content used to perform those calls.

Creating a new organization and a new user

In addition to finding and viewing Users and Organizations, you will often need to create new Users or Organizations in tasks such as new user onboarding scripts. Creating a user involves performing a POST against the Users endpoint.

A sample User creation POST is below:

POST https://vCommander.embotics.com/rest/v3/users

Body:

{
	"name": "SAMPLEUSERNAME",
	"password": "SAMPLEPASSWORD",	
	"first_name": "J",
	"last_name": "SMITH",	
	"email": "JSMITH@EXAMPLE.COM",	
	"primary_phone": "5554447777",
	"alternate_phone": "5557774444",
	"role": "NONE"
}

This POST will create a new user account using the provided details. The API will respond with the full user object in JSON which will include a link to the user account entity and the user ID value.

Note that the Role field can be changed to give this user a different role which will define access to parts of the Commander administrative and customer portals.

Valid Role values are:

Administrative Roles:

Superuser
Auditor
User
Enterprise Admin

Portal Roles

View Only
Customer
Delegated Admin
Manager
plus any Roles you have created.

The process to create an Organization is similarly simple. To create a new Organization, perform the following call:

POST https://vCommander.embotics.com/rest/v3/organizations

Body:

{
	"name": "org-name"
}

This creates an organization with the Name “ORG-NAME”. The Organization entity is returned in the response:

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

As you can see, this Organization has no Quota options configured. The Organization can have either a Cost based Quota, or a Resource based Quota, but not both.

To configure a Cost Quota for this new Organization, we would perform the following call:

PATCH https://vCommander.embotics.com/rest/v3/organizations/org-name

Body:

{
	"resource_quota": null,
	"cost_quota": {
		"daily_cost": 500,
		"allow_vm_power_on_when_over_quota": false
}

This will add a Cost Quota which allows up to 500 USD of cost per day to be used. Note that the Resource Quota, which isn’t being configured here, is set to null.

To configure a Resource Quota for this new Organization, we would perform the following call:

PATCH https://vCommander.embotics.com/rest/v3/organizations/org-name

Body:

{
	"resource_quota": {
		"num_cpus": 10,
		"memory_in_gb":40,
		"total_storage_in_gb": 500,
	},
	"cost_quota": null
}

This will add a Resource Quota which allows up to 10 CPUs, 40GB or RAM and 500GB of storage to be used. Note that the Cost Quota, which isn’t being configured here, is set to null.

Several advanced properties are available to control how the Resource Quota is calculated. Refer to the Commander API reference documentation for details on those advanced properties.

Adding a user to an organization

Once you have both an Organization and a User you can set that User as a Member of that Organization.

To do so, you perform the following call using the Username from your User creation step above and the Organization Name from the Organization creation step above:

POST https://vCommander.embotics.com/rest/v3/organizations/{Organization Name}/members

Body:

{
	"username": "SAMPLEUSERNAME",
	"is_primary_contact_for_org": false,
	"role": "MANAGER",
	"resource_quota": {
		"num_cpus": 10,
		"memory_in_gb": 20,
		"total_storage_in_gb":300,		
		]
	}
}

This will add the selected User to the Organization with a Resource Quota. You can alternatively use a Cost Quota by replacing the Resource Quota entity in the POST body with this:

	"cost_quota": {
		"daily_cost": 1000
	}

In either case, the Quota type configured for the Organization Member must match the Quota type assigned to the Organization.

Getting a list of service definitions and creating a new service request

Many scripted solutions and automated processes will need to deploy services for the user. To do this you must to find the appropriate Service Definition and then create a Service Request.

To select a specific Service Definition, you would perform the following call using the Filter feature of the Commander API:

GET https://vCommander.embotics.com/rest/v3/services?filter=name - eq ServiceName

This call will return the Service Definition for the Service named “ServiceName”. The Service Definition is returned as an element of a list named “items” as seen below:

{
	"pagination": {
		"page_size": 100,
		"page_number": 1
	},
	"items": [{
			"id": 733668,
			"name": "ServiceName",
			"type": "SERVICE",
			"links": [{
					"rel": "request-form",
					"href": 
“https://vCommander.embotics.com/rest/v3/services/733668/request-form",
					"method": "GET"
				}, {
					"rel": "service-requests",
					"href":
“https://vCommander.embotics.com/rest/v3/service-requests",
					"method": "POST"
				}
			],
		}
	],
}

Once we traverse the “items” collection and retrieve the Service Definition, we will have the service ID, which allows us to retrieve the Service Request Form and request the Service.

The Service Request Form contains the fields we can set when requesting a service. It’s a JSON representation of the actual form elements displayed in Commander when a user requests this service. Some services in a catalog may have no form. For those that do, you must retrieve the Service Request Form and use it when making the Service Request.

To get the Service Request Form make the following call and substitute the service ID from the step above for the {id} value:

GET https://vCommander.embotics.com/rest/v3/services/{ID}/request-form

The Request Form returned from that call will look like this:

{
	"service_id": 12345,
	"service": {
		"Required By": null
	},
	"components": [{
			"name": "WINDOWS SERVER 2016",
			"CPU Count": 2,
			"Memory Size": {
				"size": {
					"unit": "GB",
					"value": 16
				}
			}
		}
	]
}

The Request Form in the reply shows all the form elements that can be configured on the Service when you submit the Service Request. Some fields may be optional and some, like the CPU Count and Memory, are required to configure the VM in this example Request. The Request Form includes form elements from both the Service Form and Component Forms from the Service Definition in Commander. These are organized in the Service and Components elements in the response.

The Request Form supplies the default values for the configurable properties in the form whenever possible. For example, this Request Form will request two CPUs by default. For some properties, a default value can't be supplied by the system. For example, there is no default Required By date, so its value is null. You can edit the Request Form before submitting it and change the supplied default value for any of the properties in the form. For example, you could edit the form and change the requested number of CPUs from the default value of 2 to 4. Once the changes have been made you can submit the Service Request to request this service using the call below:

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

Body:

{
	"service_id": 12345,
	"service": {
		"Required By": "2019-02-28"
	},
	"components": [{
			"name": "WINDOWS SERVER 2016",
			"CPU Count": 4,
			"Memory": {
				"size": {
					"unit": "GB",
					"value": 16
				}
			}
		}
	]
}

The Commander API will then reply with a Service Request entity, which contains several important elements. The first element to note is the “summary” entity:

       "summary": {
		"id": 56,
		"request_type": "NEW REQUEST",
		"state": "PENDING_APPROVAL",
		"date_submitted": "2019-02-22T18:45:21Z",
		"date_required_by": "2019-02-28",
		"date_completed": null,
		"submitted_by": "apiuser",
		"assigned_to": null,
		"approvers": [],
		"waiting_on": "",
		"workflow_id": null,
		"error_message": null,
		"resource_summary": {
			"total_cpus": 1,
			"total_disk_size_kb": 41943040,
			"total_memory_kb": 4096
		},
		"cost_summary": {
			"total_categorized_cost": 0,
			"total_cost": 1120,
			"total_cpu_cost": 120,
			"total_disk_cost": 400,
			"total_extra_cost": 0,
			"total_memory_cost": 100,
			"total_os_cost": 400,
			"total_support_cost": 100,
			"total_instance_cost": 0
		}
	}

The summary contains the basic details of the Service that was requested including the name and ID of the Service Request and the cost and resource summaries. The Cost Summary section details the cost of the service broken down into the various components of the Service. The Resource Summary details the resources allocated for this Service Request such as CPU, Disk Size and Memory Size.

Following the Summary there is a Services section. This section details all the Services which were requested as part of the Request.

	"services": [{
			"service": { 
				"name": "WINDOWS SERVER 2016",

Each service in the request is listed by its name. In our example the Service is named “Basic Windows Machine”. Inside the Service we can see the Service summary, including the Service state, errors from deployment and the assigned categories.

	"service": {
		"name": "WINDOWS SERVER 2016",
		"summary": {
			"state": "READY_TO_DEPLOY",
			"workflow_id": null,
			"error_message": null,
			"categories": [
				"Windows"
			]
		},

Finally, in the Service section, there is a Configuration section. This details the Custom Attributes applied to the Service that was deployed.


	"configuration": [{
			"comments": ""
		}, {
			"SLA": "GOLD"
		}, {
			"Service Type": "PRODUCTION"
		}, {
			"Project Code": "TEST"
		}
	],

Following the Service section, there is a Components section. This details the components deployed as part of this Service Request.

	"components": [{
			"name": "SERVER2008R2",
			"summary": {
				"state": "READY_TO_DEPLOY",
				"workflow_id": null,
				"error_message": null,
				"type": "VIRTUAL_MACHINE",
				"management_server_type": "VMWARE_VC"
			},
			"configuration": {
				"memory": {
					"size": {
						"unit": "MB",
						"value": 4096
					}
				},
				"cpu_count": 2,
				"network": [{
					"name": "Adapter 1",
					"zone": "Dev"
				}],
				"disks": [{
					"name": "Hard Disk 1",
					"size": {
						"unit": "MB",
						"value": 40960
					},
					"storage_tier": "SSD SAN"
				}]
			}
		}]
	}
	],

Each Component in the Service will have a Summary and a Configuration, much like the Service itself. The Summary displays the status of the Component you requested, as well as the type of the Component. The Configuration section includes details of the Memory, CPU count and Disks, just like the Service Configuration section, but it also includes the Network configuration for this VM which is represented by this Component.

More complex Services may have multiple components which could be VMs, as we have above, or other component types depending on how the Service was configured in the Commander admin portal.

Getting a service request and reviewing the status

When a Service Request is created it typically moves through several stages which are communicated through the State field in the Service Request. When you first request the Service, it will show a State like “PENDING_APPROVAL” or “READY_TO_DEPLOY”.

In many cases, you will want to wait for the service to be fully deployed. To do that you can use the call below to get the updated Service Request and inspect the State field. The {id} parameter is the Id field from the response above:

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

This will return the same Service Request object as above but with updated values:

"summary": {
		"id": 56,
		"request_type": "NEW_REQUEST",
		"state": "COMPLETE",

Once the Service Summary State field shows the value of Complete, the service is fully deployed. If the status isn’t yet Complete you can perform the GET call on a timer and wait for the state to change.