Application Services supports REST API 2.0, including export and import APIs. REST API 1.0 is not supported.

Before you implement the REST APIs for automation purposes, verify the availability of application blueprints in the Application Services appliance user interface. You can also import application blueprints from vFabric Application Director 5.0 and 5.2, and vCloud Application Director 6.0, to the vCloud Application Director 6.0.1 appliance. You can then migrate the 6.0.1 appliance server data and agents to Application Services 6.1. You can then upgrade to subsequent releases using normal upgrade procedures.

You can also import and export application blueprints between different Application Services appliances.

For information about migrating vCloud Application Director 6.0.1 to Application Services 6.1, see Using Application Services.

For information about upgrading to the current Application Services release, see Using Application Services.

Set Up Environment

You must download and install a REST client application in your Web browser to make HTTP requests. The REST client must use valid user credentials to access the Application Services server.

Important:

You cannot simultaneously use the REST client application on a Web browser tab and log in to Application Services appliance on another Web browser tab.

Use Basic Auth to authenticate with the Application Services server. Set Content-type and Accept HTTP headers to application/json in the REST client application.

The darwin-tenant-id HTTP header is used to specify the tenant name. The value of that header is the name of a tenant. If the header is not set, then the default tenant is used to process REST calls. The default tenant name is vsphere.local.

You specify the business group of a new object by adding a special HTTP header called darwin-user-current-group. The value of the header must be the name of the business group, otherwise the REST API uses the business group of the logged-in user.

Use the dawin-user-current-group header to perform the following tasks.

  • When you request for a list of objects, you get objects from all the business groups that you access.

  • When you create a new object, you must specify the business group that the object belongs to. This is also valid for GUI.

  • You can specify business groups in two ways.

    • Use darwin-user-current-group header with the value as business group name.

    • Include the business group ID or the name in the JSON representation of the created object that you submit to the server.

All of the URIs in REST API 2.0 have the prefix https://ApplicationServicesServerIP:8443/darwin/api/2.0.

Resources

The REST API manages a set of resources, all of which are uniquely identifiable through a string identifier. The API also manages a collection of these resources. For example, the URI for a single resource instance can be https://ApplicationServicesServerIP:8443/darwin/api/2.0/ResourceTypeID. The collection of the resource might return one or more different URIs.

For a sample deployment environment instance with an ID=5, the URI is https://ApplicationServicesServerIP:8443/darwin/api/2.0/deployment-environment/5. In this example, the URIs refer to a different collection of deployment environments https://ApplicationServicesServerIP:8443/darwin/api/2.0/deployment-environment?page=1&page-size=5 and https://ApplicationServicesServerIP:8443/darwin/api/2.0/cloud-provider/4/deployment-environment.

Table 1. List of Resources and Corresponding URIs

Resource Name

Resource URI

Certificate

.../certificate/CertificateID

Cloud Provider Type

.../cloud-provider-type/CloudProviderTypeID

Cloud Provider

.../cloud-provider/CloudProviderID

Deployment Environment

.../deployment-environment/DeploymentEnvironmentID

Application

.../application/ ApplicationID

Application Version

.../application-version/ApplicationVersionID

Logical Template Version

…/logical-template-version/LogicalTemplateVersionID

Service Version

.../service-version/ServiceVersionID

Operating System Version

.../operating-system-version/OperatingSystemVersionID

Tag

.../tag/TagID

Deployment Profile

.../deployment-profile/DeploymentProfileID

Blueprint

.../blueprint/BlueprintID

Cloud Template

.../registered-physical-template/RegisteredPhysicalTemplateID

Deployment

.../deployment/DeploymentID

Deployment Task

.../deployment-task/DeploymentTaskID

Update Profile

.../update-profile/UpdateProfieID

References

REST APIs use references to resources and resource collections wherever possible to keep the data size concise and tractable. The Application Services REST API supports the following types of references.

Resource References

Point to existing resources. They include the identifier of the resource, the name of the resource, and the relative URI used to access the resource.

List References

Point to a collection of resources. List references include only a relative URI that returns a list of resources.

External References

Point to items that are external to Application Services. They include an identifier that points to an external item such as a cloud template and the name of the external resource.

HTTP Methods

The REST APIs support the following HTTP methods.

GET

Retrieve data.

POST

Modify data, perform an action, or create an object.

PUT

Modify or replace data.

DELETE

Delete data.

Concurrency Control and lockVersion

Application Services uses the lockVersion variable and an optimistic concurrency control scheme to manage user database changes. Every time the server updates a database object, it increments the lockVersion value of that object by one. The initial value of lockVersion is 0.

You can monitor the value of lockVersion to avoid overwriting changes made by someone else, and to ensure that you are using the latest version of an object. Before you post a change, retrieve the object to change. If the lockVersion value of the object has not changed since your last retrieval, then you can safely post your change. If the lockVersion value has changed, then do not post your change to the object. Instead, make your change to the latest version of the object and post it when lockVersion indicates that no change has occurred.

As an alternative, you can try to save an object without monitoring the value of lockVersion. If the value has changed, you get a concurrency exception. You then retrieve the latest version of the object, reapply the changes to that version, and repeat the save operation. The following JSON example shows a concurrency exception returned during an unsuccessful update operation.

{
  "errors": true,
  "messageList": [
    {
      "messageType": "ERROR",
      "message": "Could not perform the operation because another session
                  has modified the referenced objects.",
      "messageKey": "exceptionTranslator.optimisticLockException.generic",
      "property": null
    }
  ],
  "result": null
}

The monitoring approach reduces the chance of a concurrency exception by retrieving an object again just before saving it, but it loses some efficiency. The non-monitoring approach tries to save an object and reacts to a concurrency exception when it occurs. If few concurrency exceptions occur, efficiency increases.

Note:

Do not change the value of lockVersion. Only the server must change it.