What are the vRealize Automation APIs and how do I use them

API Services

vRealize Automation includes the following APIs. API documentation is available with the product. To access all Swagger documents from a single landing page, go to https://<vRA-HOSTNAME>/automation-ui/api-docs where vRA-HOSTNAME is the FQDN of your vRealize Automation appliance.

Table 1. vRealize Automation
Main Service	Service Name and Description
ABX	ABX Create or manage actions and their versions. Execute actions and flows.
Service Broker	Approvals Enforce policies that control required approvals for a deployment or Day 2 action before the request is provisioned.
Cloud Assembly	Blueprint Create, validate, and provision blueprints. Note: Blueprints in the API are VMware Cloud Templates in the product.
Service Broker	Catalog Access vRealize Automation Service Broker catalog items and catalog sources, including content sharing and the request of catalog items.
CMX	CMX When using Kubernetes with vRealize Automation , deploy and manage Kubernetes clusters and namespaces.
Code Stream	Code Stream Create and run pipelines for continuous delivery of your applications to production.
Cloud Assembly	Content Gateway Connect to your infrastructure as code content in external content sources, such as Source Code Management providers and VMware Marketplace.
Forms	Custom Forms Define dynamic form rendering and customization behavior in vRealize Automation Service Broker and vRealize Automation Cloud Assembly.
User Profile	Customization Configure branding information.
Service Broker	Deployment Access deployment objects and platforms or blueprints that have been deployed into the system. Note: Blueprints in the API are VMware Cloud Templates in the product.
Identity	Identity Authenticate and manage the authorization of vRealize Automation users. If you have a user role, the Identity service allows you to obtain the authorization required to manage services.
Cloud Assembly	Infrastructure as a Service (IaaS) Perform infrastructure setup tasks, including validation, and provisioning of resources in an iterative manner.
Migration	Migration Assistant Run assessments and access migration services. Supports migration of content for vRealize Automation 7.4 or later, and for NSX-V to NSX-T.
Relocation	Onboarding Define policies and plans to bring existing VMs from any cloud under management.
Service Broker	Policies Interact with policies created in vRealize Automation Service Broker.
Project	Projects Provide visibility and isolation of provisioned resources for users with a project role. Note: Swagger docs for the Platform and RBAC services are with the Projects Service.

Note: VMware provides customers with a 12 month End-of-Life notice for any breaking changes to public APIs. To review API changes, see the release notes included with the VMware vRealize Automation Documentation.

API versioning

Incremental changes to the API can affect your API clients. To ensure backward compatibility and protect your clients from the impact of an incremental change, use vRealize Automation API versioning.

API versioning allows you to lock the API to a value and control when you upgrade to a new API version. In the following example, the additional apiVersion query parameter locks the call to the API version that was in effect on January 30, 2020.

GET https://appliance.domain.com/catalog/api/sources?apiVersion=2020-01-30

It is highly recommended but not necessary to use API versioning. If you do not use API versioning, the default behavior varies depending upon the API.

For the IaaS APIs, the latest version is 2021-07-15. If you consume the IaaS APIs without versioning or if you assign a value other than 2021-07-15, requests use the version 2019-01-15.
As a best practice, lock your IaaS API requests with the apiVersion query parameter assigned to 2021-07-15 so that you ensure a smooth transition to the latest version before the version 2019-01-15 reaches its end of life. See Working with vRealize Automation Cloud Assembly APIs.
For other APIs, you can specify any date you choose for the apiVersion query parameter. If you leave the value unspecified, the latest API version is used by default. However backward compatibility is not preserved and if the API changes, you might encounter an unexpected change in the API response.
As a best practice, use the apiVersion query parameter in your API requests and lock your API to a date that most recently provided a response with expected results. Then if you want to opt-in to an API update that is announced with a new release, you can specify a new date.
For the apiVersion of the current release, see the release notes in the vRealize Automation product documentation.

How Developers Use the vRealize Automation APIs

To make API service calls, you use a browser application or an HTTP client application to send requests and review responses. The following open-source applications are commonly used:

cURL. http://curl.haxx.se
jq parser. https://stedolan.github.io/jq/
Postman application. https://www.getpostman.com/

To learn how to use the API, you can start by performing the steps outlined in the following use cases:

The use cases include curl commands in request examples. To use the commands, ensure that the jq command-line JSON processor is installed with curl. The jq parser ensures that responses are formatted for optimum readability.