vRealize Operations Cloud API

vRealize Operations Cloud API

Getting Started

Welcome to the vRealize Operations Cloud API Reference Guide. This guide contains information about the APIs that you can use to interact with vRealize Operations Cloud. This information includes API endpoints, authentication, status codes, rate limiting, and usage examples.

API Endpoints

vRealize Operations Cloud has several deployments in different geographic locations. You'll need to use the API endpoint corresponding to your geographic location. See the table below for the different API endpoints by deployment.
Deployment Endpoint
Australia (AU) https://au.www.mgmt.cloud.vmware.com/vrops-cloud/suite-api/
United States of America https://www.mgmt.cloud.vmware.com/vrops-cloud/suite-api/
Germany (DE) https://de.www.mgmt.cloud.vmware.com/vrops-cloud/suite-api/
Canada (CA) https://ca.www.mgmt.cloud.vmware.com/vrops-cloud/suite-api/
Singapore (SG) https://sg.www.mgmt.cloud.vmware.com/vrops-cloud/suite-api/
Brazil (BR) https://br.www.mgmt.cloud.vmware.com/vrops-cloud/suite-api/
United Kingdom (UK) https://uk.www.mgmt.cloud.vmware.com/vrops-cloud/suite-api/
Japan (JP) https://jp.www.mgmt.cloud.vmware.com/vrops-cloud/suite-api/
India (IN) https://in.www.mgmt.cloud.vmware.com/vrops-cloud/suite-api/

Authentication

vRealize Operations Cloud API supports VMware Cloud Services Platform (CSP) for API authentication.
Obtain a VMware Cloud API Token
Calling APIs requires an API Token and you will need to navigate to the VMware Cloud portal and create a new API Token. Your API Token will be an alpha-numeric string. You can learn more about the process in API Token Generation from the Related Files.
Using API Tokens
Once you have generated an API Token, you will use it to programmatically authorize access to APIs. Before your application can begin calling APIs, it must first make a POST request to the Cloud Services Platform (CSP) using your API Token passed with a content type of "application/x-www-form-urlencoded". Here is an example in curl. Ensure that you replace the refresh token value with your API token value. 
 curl -k -X POST 'https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize' \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'refresh_token=<refresh-token_value>'

The CSP authorize API call will return an access_token along with additional details associated with the API Token as follows:

 {
    "id_token": "...",
    "token_type": "bearer",
    "expires_in": 1799,
    "scope": "openid group_ids group_names",
    "access_token": "...",
    "refresh_token": "..."
}

In the response above, the access_token will be a character string which you will need to include as an HTTP header on all subsequent API calls using the key "Authorization CSPToken" as follows: 

 Accept: application/json
 Authorization: CSPToken <access_token_value>
Handling access_token Expiration
As part of the CSP authorize API, you will receive an expires_in key indicating the number of seconds before the access_token will expire. After this expiration period, subsequent calls to any VMware Cloud API will return the following error:
 {
    "message": "The provided token for auth scheme \"CSPToken\" is either invalid or has expired.",
    "httpStatusCode": 401,
    "apiErrorCode": 1512
}

When an API call fails with the above error, your script/program can request for a new access_token using the refresh_token provided in the initial CSP authorize call (see above). Then, you can use the same access_token to authorize the API.

Status Codes

Refer the following table for generic status codes that apply to all the APIs. For more information, see the HTTP status code registry from the Related Files.
HTTP Status Code Error Code Description
301 Moved The requested resource must be accessed through the returned URI in the location header.
401 Unauthorized The credentials could not be verified.
403 Forbidden This operation is not allowed for your account type or the user does not have the role capability to perform this action.
404 Not Found The requested resource could not be found.
405 Method Unsupported Unsupported method for URL.
415 Content Type Invalid Invalid content type.
429 Rate Limit Exceeded The API request has exceeded the rate limit. For more information, refer the Rate Limiting/Concurrency guide.
500 Internal Error Internal server error.
503 Service Unavailable Service is currently unavailable.

Rate Limiting/Concurrency

There is a configured throttle of 300 concurrent requests with an additional throttle of 50 concurrent requests from a single client (defined as an IP address).

REST API Usage Examples

To get the adapter kinds, make a GET call that returns the adapter kind collection available in the environment.

1. Make a GET call. On success, you will get back all the available adapter kinds in the response.

 {
  "adapter-kind": [
    {
      "key": "ADAPTER_KEY",
      "name": "ADAPTER_KIND_NAME",
      "adapterKindType": "TYPE",
      "describeVersion": 10,
      "identifiers": [],
      "resourceKinds": [
          "RESOURCE_KIND",
          ...
      ]
    },
      ....
  ]
}

2. Make a GET call with the desired adapter kind got from the above API call and retrieve all the resources having that adapter kind.

 {
  "pageInfo": {
    "totalCount": 1015,
    "page": 0,
    "pageSize": 1000
  },
  "resourceList": [{
    "creationTime": 1664767508088,
    "resourceKey": {
      "name": "RES_NAME",
      "adapterKindKey": "ADAPTER_KEY",
      "resourceKindKey": "RESOURCE_KIND",
      "resourceIdentifiers": [ ... ]
    },
    "resourceStatusStates": [ ... ],
                     ...,
    "identifier": "00697a47-a16b-4515-92e2-3567bc2c71e3"
  },
      ...
  ]}
}

Related Links