vRealize Operations Manager API Programming Guide The adapter instance collects data from objects in your monitored environment. The vRealize Operations Manager analytics engine processes the data and displays the complete model in the graphical interface Why Use the APl The API is most useful when there is a need to automate a well-defined workflow, such as repeating the same tasks to configure access control for new vRealize Operations Manager users. The API is also useful when performing queries on the vRealize Operations Manager data repository, such as retrieving data for particular assets in your virtual environment. In addition, you can use the API to extract all data from the vRealize Operations Manager data repository and load it into a separate analytics system rEalize Operations Manager Terminology The XML syntax you use to describe the objects for an adapter corresponds to the aPl code syntax but differs from what you find in the user interface. The following terms appear in the user interface. Included with the description of each term is the corresponding XML syntax used in an API call Adapter types Defines the adapter used to discover particular object types. For example, the vCenter adapter discovers objects connected to vSphere datacenters. The EMC adapter discovers EMC storage system objects ML syntax: adapterkinds Object types The class of entities that represent objects or information sources. Objects report data to the ealize Operations Manager analytics engine. Virtual machines, datastores, and host systems are examples of object types defined in a vCenter adapter mode XML syntax: resourcekinds Client Workflow Overview vreaLize Operations Manager Api clients implement a Rest workflow making Http requests to the server and retrieving the information they need from the server,s responses About rest REST, an acronym for Representational State Transfer, describes an architectural style characteristic of programsthatusetheHypertextTransferProtocol(http)toexchangeserializedrepresentationsof bjects between a client and a server. In the vRealize Operations Manager APl, these representations are json or xMl documents In a REST workflow, representations of objects are passed back and forth between a client and a server with the explicit assumption that neither party need know anything about an object other than what is presented in a single request or response. The URLs at which these documents are available often persist beyond the lifetime of the request or response that includes them
The adapter instance collects data from objects in your monitored environment. The vRealize Operations Manager analytics engine processes the data and displays the complete model in the graphical interface. Why Use the API The API is most useful when there is a need to automate a well-defined workflow, such as repeating the same tasks to configure access control for new vRealize Operations Manager users. The API is also useful when performing queries on the vRealize Operations Manager data repository, such as retrieving data for particular assets in your virtual environment. In addition, you can use the API to extract all data from the vRealize Operations Manager data repository and load it into a separate analytics system. vRealize Operations Manager Terminology The XML syntax you use to describe the objects for an adapter corresponds to the API code syntax but differs from what you find in the user interface. The following terms appear in the user interface. Included with the description of each term is the corresponding XML syntax used in an API call. Adapter types Defines the adapter used to discover particular object types. For example, the vCenter adapter discovers objects connected to vSphere datacenters. The EMC adapter discovers EMC storage system objects. XML syntax: adapterkinds. Object types The class of entities that represent objects or information sources. Objects report data to the vRealize Operations Manager analytics engine. Virtual machines, datastores, and host systems are examples of object types defined in a vCenter adapter model. XML syntax: resourcekinds. Client Workflow Overview vRealize Operations Manager API clients implement a REST workflow, making HTTP requests to the server and retrieving the information they need from the server’s responses. About REST REST, an acronym for Representational State Transfer, describes an architectural style characteristic of programs that use the Hypertext Transfer Protocol (HTTP) to exchange serialized representations of objects between a client and a server. In the vRealize Operations Manager API, these representations are JSON or XML documents. In a REST workflow, representations of objects are passed back and forth between a client and a server with the explicit assumption that neither party need know anything about an object other than what is presented in a single request or response. The URLs at which these documents are available often persist beyond the lifetime of the request or response that includes them. vRealize Operations Manager API Programming Guide VMware, Inc. 6
vRealize Operations Manager API Programming Guide REST API Workflows Application programs written to use a rEst Apl use Http requests that are often executed by a script or other higher-level language to make remote procedure calls that create, retrieve, update, or delete bjects that the API defines In the vRealize Operations Manager REST API, these objects are defined by a collection of Xml schemas The operations themselves are Http requests and so are generic to Http clients To write a Rest Api client application you must understand only the Http protocol and the semantics of JSoN or XML, the transfer format that the vRealize Operations Manager API uses. To use the API effectively in such a client, you must become familiar with the following concepts The set of objects that the API supports, and what they represent How the API represents these objects How a client refers to an object on which it wants to operate The API reference includes a complete list of API requests. See About the Schema Reference rEalize Operations Manager API REST Requests To retrieve object representations clients make Http requests to object references Security 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 Figure 2-2. Scenario: Provide user credentials to obtain details about alert with ID 123 REST API REST API AuthN Alert Client Service Backend GET lapi/alerts/123 Extract Auth Header User x with valid session getAlertDetails(123) 200 OK Alert Data
REST API Workflows Application programs written to use a REST API use HTTP requests that are often executed by a script or other higher-level language to make remote procedure calls that create, retrieve, update, or delete objects that the API defines . In the vRealize Operations Manager REST API, these objects are defined by a collection of XML schemas. The operations themselves are HTTP requests, and so are generic to all HTTP clients. To write a REST API client application, you must understand only the HTTP protocol, and the semantics of JSON or XML, the transfer format that the vRealize Operations Manager API uses. To use the API effectively in such a client, you must become familiar with the following concepts. n The set of objects that the API supports, and what they represent. n How the API represents these objects. n How a client refers to an object on which it wants to operate. The API reference includes a complete list of API requests. See About the Schema Reference. vRealize Operations Manager API REST Requests To retrieve object representations, clients make HTTP requests to object references. Security 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 . Figure 2‑2. Scenario: Provide user credentials to obtain details about alert with ID 123 vRealize Operations Manager API Programming Guide VMware, Inc. 7
vRealize Operations Manager API Programming Guide 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 1 You obtain valid user credentials for your vRealize Operations Manager instance, such as user name example_user, password simple_pass 2 If you want to obtain information about a resource with ID 00000000-0000-0000-2222-000000000002 you run the curl command curl-userexample_user:simple_passhttps://restendPoinT.examplecom/suite- api/api/ resources/0e000060600-0600-2222-6600000002 3Theapiserverextractscredentialsfromthehttpheaderauthorizationandcheckstheuser 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 token-based authentication scenario You obtain valid user credentials for your vRealize Operations Manager instance 2 POST a request to the REST endpoint for authentication Posthttps://restenDpoiNt.examplecom/api/token/acquire The request body includes the user name, password, and authentication source 3 In the response body, the endpoint returns the token, expiry date and time 4 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 <SS0 SAML TOKEN> 5 You can invalidate the token before the expiration date and time by sending a POST request to the out Posthttps://resteNdpoiNt.examplecom/api/token/release Request Headers The following Http headers are typically included in Api 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. 1 You obtain valid user credentials for your vRealize Operations Manager instance, such as user name example_user, password simple_pass. 2 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/suiteapi/api/resources/00000000-0000-0000-2222-000000000002 3 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. 1 You obtain valid user credentials for your vRealize Operations Manager instance. 2 POST a request to the REST endpoint for authentication. POST https://RESTendpoint.example.com/api/token/acquire The request body includes the user name, password, and authentication source. 3 In the response body, the endpoint returns the token, expiry date and time. 4 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> 5 You can invalidate the token before the expiration date and time by sending a POST request to the logout endpoint. POST https://RESTendpoint.example.com/api/token/release Request Headers The following HTTP headers are typically included in API requests: vRealize Operations Manager API Programming Guide VMware, Inc. 8
vRealize Operations Manager API Programming Guide Accept-Language To specify the language desired in responses, use the Accept-Language request header Message strings in Error Type responses are localized To request a response with message strings localized to French, use the following header: ccept-Language: fr-FR Authorization All requests to create an API session must include an Authorization header of the fom prescribed by the identity provider that your organization uses Content-type Requests that include a body must include an appropriate Http Content-type header For a request body in XML, the header must include Content-Type: application/xmL s For a request body in JSON, the header must include Content-Type: application/json Accept To specify the desired response format, include the Accept request header For a response in XML, the header must include Accept: application/xml s For a response in JSON the header must include Accept: application/json 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 dentifying 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 vRealize operations Manager API REST Responses All responses include an Http status code and unless the status code is 204(no cOntent), an Accept header Response content depends on the request. Some responses include a document body, some include only a URL, and some are empty Http Response Codes An Apl client can expect a subset of Http status codes in a response Table2-1.httpStatusCodesthattheaplreturns Status Code Status Descriptic 260K The request is valid and was completed. The response includes a document body 201 Created The request is valid. The requested object was created and can be found at the URL specified in the Location header. 02 Accepted The request is valid and a task was created to handle it. This response is usually accompanied by a TaskStatus element
Accept-Language To specify the language desired in responses, use the Accept-Language request header. Message strings in ErrorType responses are localized. To request a response with message strings localized to French, use the following header: Accept-Language: fr-FR Authorization All requests to create an API session must include an Authorization header of the form prescribed by the identity provider that your organization uses Content-Type Requests that include a body must include an appropriate HTTP Content-Type header. n For a request body in XML, the header must include Content-Type: application/xml n For a request body in JSON, the header must include Content-Type: application/json Accept To specify the desired response format , include the Accept request header. n For a response in XML, the header must include Accept: application/xml n For a response in JSON, the header must include Accept: application/json 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: n XML namespace attributes must be supplied for all namespaces represented by elements in the request. n 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. n 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. vRealize Operations Manager API REST Responses All responses include an HTTP status code and, unless the status code is 204 (No Content), an Accept header. Response content depends on the request. Some responses include a document body, some include only a URL, and some are empty. HTTP Response Codes An API client can expect a subset of HTTP status codes in a response. Table 2‑1. HTTP Status Codes that the API Returns Status Code Status Description 200 OK The request is valid and was completed. The response includes a document body. 201 Created The request is valid. The requested object was created and can be found at the URL specified in the Location header. 202 Accepted The request is valid and a task was created to handle it. This response is usually accompanied by a TaskStatus element . vRealize Operations Manager API Programming Guide VMware, Inc. 9
vRealize Operations Manager API Programming Guide Table 2-1. Http Status Codes that the apl reTurns(continued) Status Code Status Descripti 204 No Content The request is valid and was completed. The response does not include a bod 400 Bad Request The request body is malformed, incomplete, or otherwise 401 Unauthorized Login failed or authentication token has expired 403 Forbidden The user is not authenticated or does not have adequate privileges to access one or more objects specified in the equest 404 Not Found The object specified in the request could not be found. 405 Method Not Allowed The Http method specified in the request is not supported for 406 Not Acceptable The resource identified by the request is not capable of generating a response of the type specified in the requests Accept header. 415 Unsupported Media Type The resource identified by the request does not support a request of the specified Content-type and Http method 422 Not Found Usually indicates a malformed request URL or request body. 429 Too Many Requests a client has sent too many requests or multiple clients are sending too many simultaneous requests and the server is unable to process them due to rate limits. To work around the problem, try sending the request again 500 Internal Server Error The request was received but could not be completed because 503 Service Unavailable The server is currently unable to handle the request due to a temporary condition such as resource exhaustion or server 504 Gateway Timeout The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the request URL. Using the APi with VMware vRealize operations manager VMware vRealize Operations Manager 6.0 and later versions support the vRealize Operations Manager Rest Apl. You can use a browser or an Http client program to send requests and receive responses REST Client pr。 grams Any client application that can send HT TPS requests is an appropriate tool for developing REST applications with the VMware vRealize Operations Manager APl. REST client plug-ins are available for most browsers and many IDES. The following open-source programs are commonly used CurL.http://curl.haxx.se
Table 2‑1. HTTP Status Codes that the API Returns (Continued) Status Code Status Description 204 No Content The request is valid and was completed. The response does not include a body. 400 Bad Request The request body is malformed, incomplete, or otherwise invalid. 401 Unauthorized Login failed or authentication token has expired. 403 Forbidden The user is not authenticated or does not have adequate privileges to access one or more objects specified in the request. 404 Not Found The object specified in the request could not be found. 405 Method Not Allowed The HTTP method specified in the request is not supported for this object. 406 Not Acceptable The resource identified by the request is not capable of generating a response of the type specified in the request's Accept header. 415 Unsupported Media Type The resource identified by the request does not support a request of the specified Content-Type and HTTP method. 422 Not Found Usually indicates a malformed request URL or request body. 429 Too Many Requests A client has sent too many requests or multiple clients are sending too many simultaneous requests and the server is unable to process them due to rate limits. To work around the problem, try sending the request again later. 500 Internal Server Error The request was received but could not be completed because of an internal error on the server. 503 Service Unavailable The server is currently unable to handle the request due to a temporary condition such as resource exhaustion or server maintenance. 504 Gateway Timeout The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the request URL. Using the API with VMware vRealize Operations Manager VMware vRealize Operations Manager 6.0 and later versions support the vRealize Operations Manager REST API. You can use a browser or an HTTP client program to send requests and receive responses. REST Client Programs Any client application that can send HTTPS requests is an appropriate tool for developing REST applications with the VMware vRealize Operations Manager API. REST client plug-ins are available for most browsers and many IDEs. The following open-source programs are commonly used: n cURL. http://curl.haxx.se vRealize Operations Manager API Programming Guide VMware, Inc. 10