To retrieve object representations, clients make HTTP requests to object references.
The HTTP link between an API client and server is established using SSL. API clients configure either basic authentication or token-based authentication to communicate with the server. If token-based authentication is used, the API client must complete a login request to receive an authentication token that is included in all subsequent requests .
With basic authentication, you must pass valid user credentials with every API request. To prevent user credentials from being passed as clear text, the vRealize Operations Manager API server supports HTTPS communication only . The following example presents a basic authentication scenario using curl.
You obtain valid user credentials for your vRealize Operations Manager instance, such as user name
If you want to obtain information about a resource with ID 00000000-0000-0000-2222-000000000002, you run the curl command:
curl --user example_user:simple_pass https://RESTendpoint.example.com/suite-api/api/resources/00000000-0000-0000-2222-000000000002
The API server extracts credentials from the HTTP header authorization and checks the user credentials. If the credentials are valid, it performs a read operation and returns the requested information about the resource.
With token-based authentication, you POST a login request to the vRealize Operations Manager API server, supplying valid user credentials to obtain an authentication token. The following example presents a token-based authentication scenario.
You obtain valid user credentials for your vRealize Operations Manager instance.
POST a request to the REST endpoint for authentication.
The request body includes the user name, password, and authentication source.
In the response body, the endpoint returns the token, expiry date and time.
For further communication, you include the token object in the Authorization header with the format :
Authorization: vRealizeOpsToken <vROps_token>
Alternatively, if you acquired the token from an SSO source, the Authorization header is of the format:
Authorization: SSO2Token <SSO_SAML_TOKEN>
You can invalidate the token before the expiration date and time by sending a POST request to the logout endpoint.
The following HTTP headers are typically included in API requests:
To specify the language desired in responses, use the
All requests to create an API session must include an
Requests that include a body must include an appropriate HTTP
To specify the desired response format , include the
Request Bodies in XML
For a request body written in XML, vRealize Operations Manager uses a validating XML parser that requires elements in a request body to agree with the schema in order and number . Request bodies are rejected as invalid unless they meet the following criteria:
XML namespace attributes must be supplied for all namespaces represented by elements in the request.
If multiple namespaces are represented in the request, XML namespace attributes must include an identifying prefix, and that prefix must be used with all elements from that namespace.
All required elements must appear in request bodies. All elements that appear in request bodies must appear in the order that the schema establishes, and with content that conforms to the type constraint that the schema specifies.