Programmatic access to Advanced Networking Services consists of consuming the vCloud Air Platform API to log in and create a session and the Advanced Networking Services API to manage your networking and edge gateways.

To use the Advanced Networking Services API, VMware recommends that you use the following RESTful workflow to programmatically manage networking for vCloud Air with Advanced Networking Services.

Note

Before you access the Advanced Networking Services API, you must meet the API prerequisites. See Prerequisites for using the RESTful API for information.

At a high level, you will follow these super-steps:

1

The vCloud Air APIs include calls to log in and get the details of available virtual data centers from the vCloud API.

The responses to these calls include endpoints and a session token. With those credentials, you can call the Advanced Networking Services API without needing to provide the credentials again. You can automate your workflows without having to store the credentials on disk or in memory.

Required:

All the Advanced Networking Services RESTful requests require the authentication token you receive after logging in and creating a session.

2

Using the vCloud API, query vCloud Director for the ID of the edge gateway you require configuration details about. For information, see Querying the vCloud API.

RESTful systems interface with external systems as Web resources identified by Uniform Resource Identifiers (URIs), for example /nat/config, which can be operated upon by using standard HTTP verbs such as GET and POST. The complete resource consists of the following URI, which requires that you know the specific edge gateway ID for the operation: 

http://serverAddress/hybridity/api/gateways/gatewayId/operation
3

Using the edge gateway ID, submit a GET request to query Advanced Networking Services for the properties of the object you are configuring.

A client can “read” an object by making an HTTP GET request to the object’s resource URL. If the request is successful, the server returns HTTP response code 200 and a JSON document of the specified configuration.

4

Examine the response. Extract the JSON elements from the response body of the GET call and modify them as required.

5

Pass the modified JSON elements as the request body in a PUT or POST call.

A client can “write” (create or modify) an object with an HTTP PUT or POST request that includes a new or changed JSON body document for the object.

Not all object elements are required when sending the PUT request. The schema descriptions in this guide document which elements are required. All the optional elements are safe to ignore while sending the updated configuration to the server.

For example, if an IP set is referenced in a firewall rule, only ipSet and type are needed in the source and destination objects and not name and isValid elements.

When sending a POST request, IDs for new objects should be removed or set to zero.

If new entities are sent in the request, the response will contain the system-generated IDs, which are assigned to these new entities. These IDs identify the resource and can be used in the URIs if you want to operate on these entities.