Introduction

The vFabric Data Director API supports programmatic implementation of the following calls, in order to extend or emulate the Data Director client.

Definitions

Resource: the piece of data, or area of functionality, under manipulation
Verb: HTTP verb. We use the following mapping:
- Create operations: POST (to container where the object will be created)
- Read operations: GET (to object you want to read)
- Update operations: PUT (to object you want to update)
- Delete operations: DELETE (to object you want to delete).
- Note that PUT and DELETE will not cause harm if you call them more than once.
URI: the Universal Resource Identifier, or name where the resource can be manipulated.
Request Body: the request data that you must supply programmatically. This API supports request bodies that use application/xml, application/json, or text/plain media types. You can see examples of XML and JSON fields for each call in the Call Reference below, or you can look at the sample types at https://.../datadirector/api/dataformat.

Making A Call

As with most REST APIs, you need to perform the following steps to implement each call.

Create a string for the http request that consists of the following format [HTTP verb][url] + [headers] + optional [Request Body].
Use your language's network library (or higher level http library) to send the request to your Data Director http server.
Authentication. For authentication, REST APIs accept HTTP Basic authentication on each request, encoded with an existing Data Director username/password credential.
Read the response/callback using your programming language.
Use your programming language to parse the XML or JSON data within the response.
Use the data in your applications.

Headers

The vFabric Data Director API supports standard HTTP headers. The server returns the requested data as XML or JSON values depending on the format you specify in the HTTP headers as follows:

Content-type: The value of the context-type header is application/xml or application/json, depending on which request format you use. The content-type header must be used with PUT/POST requests that include a request body.
Accept: The value of the Accept header is application/xml or application/json, depending on which return format you require. The Accept header must be used with GET requests that expect a response body in return.
Authorization: HTTP basic authentication (RFC 2617).
Location: Requests that create an object (including all async requests, which create a task object), return the created object's URL via this header.

Synchronous vs. Asynchronous Operations

Some of the calls in the vFabric Data Director API return data immediately, others return a status, and some return both a status and a URL. When you receive a "202 Accepted" status and a task URL, this is an asynchronous response and you must poll to find out the results of the call. Use GET followed by the URL to retrieve the results of an asynchronous response.

Requesting a List

Use the GET verb with any of the ‘Enumerate’ calls in the Call Reference below (collection URLs). This will return a list of URLs that contain the names of the objects in a collection. Use the GET verb again with each of the URLs to retrieve the data for a specific object. All collection URLs are returned as application/xml, application/json, or text/plain media types

API Versioning

The vFabric Data Director API supports versioning through HTTP Accept/Content-Type headers. E.g. if you want 2.0 version APIs, append the vFDD version prefix to standard media type in request Accept header, like "Accept: application/vnd.vmware.vfdd-v2.0+json", then 2.0 version content will respond with versioned Content-Type response header, like "Content-Type: application/vnd.vmware.vfdd-v2.0+json". If no version prefix is carried by Accept header, then the latest version content will respond.

See vFabricDataDirectorProgrammingGuide2.0.pdf for more detailed information about using the vFabric Data Director 2.0 API, and see the Release Notes for any known issues, tips, or updates.

REST Resources

This API supports a Representational State Transfer (REST) model for accessing a set of resources through a fixed set of operations. The following resources are accessible through the RESTful model:

Data Model

All endpoints act on a common set of data. The data can be represented with difference media (i.e. "MIME") types, depending on the endpoint that consumes and/or produces the data. The data can described by XML Schema, which definitively describes the XML representation of the data, but is also useful for describing the other formats of the data, such as JSON.

This document will describe the data using terms based on XML Schema. Data can be grouped by namespace, with a schema document describing the elements and types of the namespace. Generally speaking, types define the structure of the data and elements are instances of a type. For example, elements are usually produced by (or consumed by) a REST endpoint, and the structure of each element is described by its type.

Data Elements

Namespace URI:	(default namespace)
XSD:	vfdd-rest.xsd