The HPE OmniStack REST API is available on every Virtual Controller. To issue a REST request, target the network address (IP address or DNS name) of the Virtual Controller. The REST API provides a secure portal into the Virtual Controller. Consequently, address REST API requests to secure port 443. The following diagram illustrates the basic architecture of the REST API:
The REST API object model enables you to monitor and manage a set of HPE OmniStack objects, including backups, datastores, hosts, clusters, policies, tasks, and virtual machines. The following table describes each of the types of objects that the REST API supports:
A complete, standalone image of a virtual machine, taken at a specific point in time. You can retrieve all of the backups that are defined in the federation. You can copy, delete, lock, rename, restore, and set the retention time for backups.
A repository that contains the files of one or more virtual machines. You can retrieve all of the datastores that are defined in the federation. You can create new datastores, and you can delete, resize, and set policies for existing datastores.
An HPE OmniStack host in a federation. You can retrieve all of the hosts that are defined in a federation along with their capacity, hardware, and metrics data.
A logical grouping of systems that are running the HPE OmniStack software. You define an
Contains backup rules that can be applied to an individual datastore or virtual machine. You can retrieve all the policies that are defined in the federation. You can create, delete, and rename policies. You can also create, edit, and delete the rules associated with policies.
Tracks the progress of an HPE OmniStack operation. When the status of a task is
Represents a single virtual machine that has been created within an HPE OmniStack datastore. You can retrieve all of the virtual machines in the federation. You can back up, clone, and move virtual machines. You can set policies for virtual machines and retrieve virtual machine backup and metrics data.
REST API object type relationships
The REST API supports the relationship of one object to another object of a different type by referencing the ID of the related object as a value of one of the properties of the base object. The following figure shows these object type relationships:
REST API tasks as managed objects
The control plane treats tasks as true managed objects, which enables clients to efficiently determine the changes that requests have made on the system; for example, during the creation of new objects. Tasks contain meaningful information that enables clients to post-process requests in an intuitive and deterministic manner. The REST API task managed object has the following characteristics:
- A task has an ID value that enables a client to query for a task.
- The state of a task conveys where the task currently is in the processing sequence. Based on the current state, other properties of the task might not be set.
- If the task ends in failure, the
messageproperties contain information about the failure.
- If the task completes successfully, the
affected_objectsarray contains information about the object(s) that the task impacted. Each
affected_objectentry has a type-significant ID, as well as a type string. For example, if the move of a virtual machine completes successfully, the task that is associated with the move has an
virtual_machinetype, and the ID of the task is the system-assigned ID of the new virtual machine.
affected_objectscan be associated with a task (thus, the array of affected_objects).