I seem to spend a lot of my time responding to queries about the vRealize Automation API these days. That being the case, I thought it might be worth starting to put together a few blog posts to address some of the common use cases that people are looking to deliver.
Anatomy of a vRA API call.
Methods
vRealize Automation uses four of the available HTTP methods.
- GET
- POST
- PUT
- DELETE
Headers
vRealize Automation requires the following headers:
- Accept : application/json
The Accept request-header field can be used to specify certain media types which are acceptable by the recipient of the response. - Content-Type: application/json
The Content-Type header indicates the media type of the body that will be sent to the recipient. It can be thought of as a declaration “here is what I am sending you”. In theory, you only need to include this header for POST/PUT calls where you need to inform the recipient of what is being sent, but in practical terms it is simpler to include this for all requests. - Authorization: Bearer tokenId
The Authorization field value consists of credentials containing the authentication information of the user agent for the realm of the resource being requested. In the case of vRA, a “realm” would be a specific tenant.
Based on the roles assigned to the account that you authenticate with certain URIs or methods may not work. In these cases you will receive a 403 (forbidden) response from the server.
URI
Each function you want to perform requires interaction with one or more URIs (universal resource identifiers – sometimes referred to as URLs or API endpoints) for each of the services listed below. These URIs support one or more of the methods listed above, and as mentioned previously require you to have appropriate permissions to interact with them.
Services
While there isn’t 100% coverage of vRA functionality through the API, a large number of services are exposed. These include:
- Advanced-Designer-Service
- Approval-Service
- Branding-Service
- Catalog-Service
- Component-Registry
- Composition-Service
- Container-Service
- Content-Management
- Endpoint-Configuration-Service
- Event-Broker-Service
- Forms-Service
- Iaas-Proxy-Provider
- Identity
- IPAM-Service
- Licensing-Service
- Management-Service
- Network-Service
- Notification-Service
- o11n-Gateway-Service (Orchestration)
- Placement-Service
- Plugin-Service
- Portal-Service
- Properties-Service
- Reservation-Service
- Software-Service
- Workitem-Service
Body
In the case of both POST and PUT, you need to provide some data for the call to use as an input. This is referred to as a Body. Note that we also refer to information that we receive back from a request as the Body of the response.
Status Codes
When you submit a request, you may not receive a Body in response from the server. What you will always receive is a Status Code. This is helpful in identifying whether a request was successfully submitted, but doesn’t always correlate to a request being successfully processed. More on that later.
Status Codes are also handy when attempting to figure out why something hasn’t worked. A 401 means you aren’t authenticated. A 403 means you don’t have the appropriate permissions to do what you are trying to do. A 404 on the other would indicate that the URI you are attempt to use doesn’t exist – maybe you’ve made a typo.
How do I figure it all out?
As of vRA 7.1, you can navigate to https://vra-fqdn/component-registry/services/docs and you will get the new API documentation on SwaggerUI. This shows all the available URIs for each service, and for calls that require specific parameters to be included with the body, this information is also included.
Next up, we will get you setup with Postman (a REST client) and begin looking at some examples.
Further reading:
Understanding HTTP methods using a coffee order as an example.
Back to where it all started – Roy Fielding on REST APIs. This is super interesting… but maybe I’m just a geek.