Using the RESTful web API
To issue a RESTful web API request, send an HTTP POST request with the Content-Type:text/xml header to the computer where the BMC VaraLogix Q Deployment Automation is currently running. The HTTP POST request URL is http://server/brlm/index.php/api/processRequest.xml, where server is the servername of the machine where the BMC VaraLogix Q Deployment Automation is installed.
The request body looks in the following way:
<request command="command">
<arg>argument</arg>
<arg>argument</arg>
</request>
</q>
The auth_token is either the authentication token, or the user login and password separeted by a space.
For information about the commands that you can invoke through the RESTful API interface, see Commands.
After the system processes a request, it adds a <result> block to the original request and passes the results back to the caller, including the following information:
- result code rc that indicates the status of request
- message that explains the status code (for example, Ok)
- any response content generated by the request (for example, a list of system users)
The following example shows the format of the <result> block:
<request command="user list" />
<result rc="0" message="Ok">
<response id="1" value="_system" />
<response id="2" value="root" />
</result>
</q>
In cases where information is queried and multiple items are returned as a result (for example, with user list), the result contents are split into the <response> lines that include an ID and value attributes. Every response block corresponds to a record that satisfied the request. The value of ID attribute is a unique identifier that should be used for subsequent operations with the returned data.
Error handling
To ensure that the command execution succeeded, check the rc attribute in the <result> tag. When rc value is zero, the request was processed without errors. For more information about the result codes, see API-result-codes.
A non-zero rc value indicates that request processing has failed, and the message attribute contains explanation of the reason for the failure, as shown in the following example:
<request command="create instance">
<arg>1</arg>
</request>
<result rc="7" message="Incorrect arguments to command">
<response />
</result>
</q>
In this example, the create instance command that requires the package ID and the deployment route arguments is launched with the second argument missing.
After correcting the arguments, the command succeeds, as shown in the following example:
<request command="create instance">
<arg>1</arg>
<arg>home/</arg>
</request>
<result rc="0" message="Ok">
<response id="7" value="Created instance Sample Package_0.0.0.1" />
</result>
</q>