vRealize Orchestrator Server API
vRealize Orchestrator REST API
What Is the vRealize Orchestrator REST API?
With the vRealize Orchestrator REST API, you can communicate with the vRealize Orchestrator server directly through HTTP. The API exposes the objects from the vRealize Orchestrator server inventories and the installed plug-ins as resources at predefined URLs, and API consumers can trigger operations in vRealize Orchestrator by making HTTP calls at these URLs.
Typical Use Cases
You can use the vRealize Orchestrator REST API to:
- Run a workflow, schedule a workflow, retrieve the runs of a workflow, respond to a user interaction, and cancel a workflow run.
- Retrieve details about a workflow such as its input and output parameters and its presentation.
- Retrieve details about a workflow run such as its state, generated logs, start date, and end date.
- Browse through the vRealize Orchestrator inventories and the installed plug-ins.
- Import and export workflows, actions, and packages.
Key Concepts
Resource
A resource is an object with a type, associated data, relationships to other resources, and a set of methods that are used to perform operations. Only a few standard methods are defined for the resource, which correspond to the standard HTTP GET, POST, PUT and DELETE methods.
Statelessness
The vRealize Orchestrator REST API is stateless, which means that the information required to process a request is included in the request.
How the vRealize Orchestrator REST API Works
The API supports a Representational State Transfer (REST) model for accessing a set of resources through a fixed set of operations. Every request to the vRealize Orchestrator REST API must be authorized by an authenticated user. Depending on whether you configure vRealize Orchestrator with LDAP, vCenter Single Sign-On, or OAuth2, the authentication scheme for the vRealize Orchestrator REST API is different.
LDAP Authentication
When vRealize Orchestrator is configured with LDAP, you must apply the HTTP Basic authentication scheme. With the HTTP Basic authentication scheme, you can authenticate against vRealize Orchestrator or a third-party system by including an Authorization header in every HTTP request. You must provide a base64-encoded user name and password in the Authorization header. For details about the HTTP Basic authentication, see RFC 2617. The REST resources expose a data model, supported by a set of client-side libraries that are available in the local Maven repository of vRealize Orchestrator.
Single Sign-On Authentication
If vRealize Orchestrator is configured with the vCenter Single Sign-On (SSO) server, you need a principal holder-of-key (HoK) token to access system objects in vRealize Orchestrator through the REST API. The HoK token is passed as a request Authorization header element. The value must be a GZIP, base64-encoded string.
OAuth2 Authentication
If vRealize Orchestrator is configured with VIDM, you need an OAuth bearer access token to access system objects in vRealize Orchestrator through the REST API. The OAuth bearer token is passed as an Authorization header element request. The value must be Bearer {token}.
Data Model
All endpoints act on a common set of data. The data can be represented in different content types, depending on the endpoint that consumes or produces the data. An XML Schema describes the data, its XML representation, and the other formats of the data, such as JSON. Data can be grouped by namespace, with a schema document describing the elements and types of the namespace. Elements are instances of a type and types define the structure of the data. For example, elements are produced by a REST endpoint, and the structure of each element is described by its type. To test the service bellow, you must enable basic authentication over vCenter Single Sign-On (SSO). To enable basic authentication over vCenter Single Sign-On (SSO), add the following line in the vmo.properties configuration file:
com.vmware.o11n.sso.basic-authentication.enabled = true
Additional Information
For additional information and details on the REST APIs, see Developing a Web Services Client for VMware vRealize Orchestrator at the following URL: