Using the REST API Documentation

View documentation for each REST API:

http://www.vmware.com/support/developer/vas/rest-api-1.0.2.RELEASE/index.html

The vFabric Administration Server API tab is selected in the following illustration.

Each command in the API is summarized on one line with four parts:

Operation

The HTTP operation: GET, POST, or DELETE. GET commands are displayed in blue, POST commands in green, and DELETE commands in red.

URI

Location of the resource on the server. A pair of braces {} in the path is a placeholder for a specific entry in a list; it is an integer assigned when the resource is created by the server.

Description

Short summary of the command.

Permission

Permission required to execute the command: READ, WRITE, or EXECUTE.

Click a command to expand it and view detailed documentation, as in the following illustration.

The expanded documentation begins with a longer description of the command. The details of the HTTP request and response are described in the sections beneath the description.

Request Payload

The Request Payload section describes the content of the request payload for a POST command. The content type is in parentheses in the heading. The request payload can contain data in the form of a JSON document, a text or XML document, a binary file such as a ZIP file, or a combination, in a multipart message.

The tables in this section of the documentation describe the expected content of the payload and the valid values. It is helpful to refer to the Example section to see a sample of the payload in an HTTP request.

Response Payload

The Response Payload section describes the data the server returns in response to a request. Often, the response payload is a JSON document, but depending on the request, it may be an XML or text document, such as a configuration file or log file.

The tables in this section describe the content of the response payload. When a JSON document in the payload contains an array of objects, the object is described in a separate table and referenced from the table containing the array.

The Examples section of the API documentation contains a sample of a typical response payload.

Successful Outcomes

The Successful Outcomes section lists HTTP response codes returned for successful requests.

A 200 response code indicates that the server has completed the request. This is the expected code for a GET request when the resource is successfully returned in the response payload.

A 201 response code is returned when the server has created a resource. The response Location header contains the URI of the new resource.

A 202 response code is returned when the server creates a task to perform the request. For example, creating an installation on a group creates a task on the server. A URI for the task is returned in the Location header of the response. Monitor this URI to see the status of the task move from PENDING, to IN_PROGRESS, and finally to SUCCESS or FAILURE. Any resources created by the task are identified in the response payload.

Note

Delete a task when you finish processing the result.

Exceptional Outcomes

The Exceptional Outcomes section lists the HTTP response codes that can be returned when a request fails. Response codes in the 400 range describe problems with the request, such as data missing from the request, a URI that does not exist, or a violation of some documented constraint.

Response code 500, "An unexpected server-side error occurred," is an abnormal response indicating that something has gone wrong on the server requiring further investigation.

Examples

The Examples section of the API documentation contains an example of a typical request and response. It is useful to view the content and format of the HTTP request and the payloads. Some commands have multiple examples that demonstrate varying responses to different states on the server. For example, the GET /vfabric/v1/tasks/{}/ command includes examples of the responses as a task moves through its execution phases.