HPE Developer Community Portal
About the API
Explore the API
Use the API
Manage certificates using PowerShell
HPE OmniStack hosts are managed within a federation that represents a group of networked HPE OmniStack hosts. A federation enables you to manage your hyperconverged infrastructure deployed in multiple sites as a single entity. Federations are configured as one of the following:
- Centrally-Managed: Supports larger federations. It includes a virtual machine called the Management Virtual Appliance. The Management Virtual Appliance is a dedicated virtual machine that provides centralized management and coordination of operations across clusters of HPE OmniStack hosts for high-scale configurations. You can deploy a centrally-managed federation or convert an existing peer-managed federation.
- Peer-Managed: You can deploy and manage a single vCenter Server with 32 HPE OmniStack hosts. To scale beyond 32 hosts, you can leverage Enhanced Link Mode and link three vCenter Servers with 32 HPE OmniStack hosts in each vCenter Server.
The HPE OmniStack REST API is available on every Virtual Controller and the Management Virtual Appliance in centrally-managed federations. To issue a REST request, target the network address (IP address or DNS name) of the REST Server IP address.
- On peer-managed federations, the REST Server IP address is the Virtual Controller Management IP address.
- On centrally-managed federations, the REST Server IP address is the Management Virtual Controller IP address. The Management Virtual Appliance provides a holistic view of the federation.
Address REST API requests to secure port 443.
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.|
|External stores enable you to asynchronously back up your primary data to an on-premise device such as HPE StoreOnce.|
|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.|
|Manages SSL certificates in HPE SimpliVity trust stores.|
|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).