Content Subscription Endpoint Specification

Introduction

VMware Cloud Director™ enables organizations to create catalogs that acquire their content from a subscription to an external source. The external source can be an externally published catalog hosted on another instance of VMware Cloud Director or a Web site that hosts a VCSP endpoint.

Configuration parameters for VMware Cloud Director catalogs that have external subscriptions include a VCSP endpoint URL and, if the endpoint requires authentication, a user name and password. Users periodically synchronize to update catalog contents from the subscribed endpoint. You can request synchronization for an entire catalog, or for individual catalog items. The process is similar in both cases.

The VCSP client makes a GET request to retrieve the endpoint descriptor. If the version in the descriptor matches the version of the catalog being synchronized, no content has changed at the endpoint, and no further action is required.
If the version in the descriptor is greater than the version of the catalog, the client makes a GET request to retrieve the endpoint index file.
To update the entire catalog, the client makes GET requests to retrieve all catalog items whose version at the endpoint is greater than their version in the catalog. To update an individual catalog item, the client makes a GET request to retrieve it only if its version number at the endpoint is greater than its version in the catalog.

The endpoint is a passive partner in this process. Its only responsibilities are to keep the version numbers up to date in the endpoint descriptor and endpoint index files, and to return the HTTP status codes and other responses expected by the VCSP client.

URLs

A VCSP endpoint URL must have a scheme of HTTP or HTTPS and a path that terminates in the name of the endpoint descriptor. A VCSP endpoint whose contents are stored on a host named vcsp.example.com in a directory named /vcsp on the host and whose descriptor file is named descriptor.json would have the following endpoint URL:

http://vcsp.example.com/vcsp/descriptor.json

Endpoint Descriptor

The endpoint descriptor is a file whose contents define the catalog available at the endpoint. The contents, which must be expressed in JavaScript Object Notation (media type application/json) as defined by RFC4627, define a JSON object, and must specify values for the following key names.

vcspVersion

An integer that specifies the version of the VCSP protocol to which this endpoint conforms.

version

An integer that specifies the version of the catalog, as described in Version Numbers.

id

The object identifier, expressed in URN format. This value uniquely identifies the catalog, persists for the life of the catalog, and must never be reused.

name

The display name of the catalog. Must be a nonempty string.

created

Time and date when the endpoint was created.

itemType

Must have value vcsp.CatalogItem.

itemsHref

A reference to the endpoint index file relative to the location of the endpoint descriptor. Replacing the final component of the endpoint URL with the value of the itemsHref key must create a valid URL.

capabilities

A JSON object that describes the capabilities of this catalog. The object must define all of the following properties:

transferIn: An array with a single member that must be the string httpGet.
transferOut: An array with a single member that must be the string httpGet.
generateIds: A Boolean value that must be set to true.

metadata

An array of catalog object metadata. See Metadata.

maintenanceMessage

A string indicating that the endpoint is inaccessible because it is undergoing maintenance. For example:

"maintenanceMessage" : "This catalog is currently in maintenance mode"

If the endpoint descriptor includes this key, attempts by subscribers to synchronize with this endpoint fail and display the string.

The following example shows a typical endpoint descriptor.

{
  "vcspVersion" : "1",
  "version" : "10",
  "id" : "urn:uuid:ccdd2c56-e54e-4883-bc0a-619baaca92a6",
  "name" : "published",
  "created" : "2012-09-14T22:17:50.807Z",
  "itemType" : "vcsp.CatalogItem",
  "itemsHref" : "items",
  "capabilities" : {
    "transferIn" : [ "httpGet" ],
    "transferOut" : [ "httpGet" ],
    "generateIds" : true
  }
   "metadata" : [ {
    "type" : "STRING",
    "domain" : "GENERAL",
    "key" : "key1",
    "value" : "value1",
    "visibility" : "READWRITE"
  }, {
    "type" : "STRING",
    "domain" : "SYSTEM",
    "key" : "key2",
    "value" : "value2",
    "visibility" : "READONLY"
  } ]
}

Endpoint Index

The endpoint index is a file whose contents define the set of items available in the catalog. The contents, which must be expressed in JavaScript Object Notation (media type application/json) as defined by RFC4627, define a JSON object, and must specify values for the following key names.

itemType

Must be vcsp.CatalogItem.

items

An array of zero or more item objects. Each item object must specify values for the following key names.

version

An integer that specifies the version of the item, as described in Version Numbers.

id

The object identifier of the item, expressed in URN format. This value uniquely identifies the item, persists for the life of the item, and must never be reused.

name

The display name of the item. Must be a nonempty string.

created

Time and date when the item was created.

type

Item type. Must have one of the following values:

vcsp.iso if the item is an ISO image.
vcsp.ovf if the item is an OVF package.

files

An array of file objects that includes all the files that represent the item. Each file object is represented as an array with three elements:

etag: An integer representing the version of the file. The value of this key must be the same for each file in the array. When any file in this array gets updated, you must increment the value of the etag key for all files in the array.
name: The name of the file.
hrefs: An array of pathnames to the file. Must contain a single pathname to the file from the root of the endpoint, written as a URL fragment.

properties

An array of additional properties of the item. This array has a single member:

selfHref: A URL to the item descriptor for this item. See Item Descriptors.

metadata

An array of catalog item metadata. See Metadata.

vms

If this item represents a vApp template, you must include an array representing the virtual machines referenced in the template.

name: The name of the virtual machine.
metadata: An array of virtual machine metadata. See Metadata.

version

An integer that specifies the version of the endpoint index, as described in Version Numbers.

The following example shows a typical endpoint index.

{
  "itemType" : "vcsp.CatalogItem",
  "items" : [ {
    "version" : "1",
    "id" : "urn:uuid:6dfa4596-a7c5-4d62-9a84-c559968baa26",
    "name" : "vapp-demo",
    "created" : "2012-09-17T17:59:15.161Z",
    "type" : "vcsp.ovf",
    "files" : [ {
      "etag" : "37"
      "name" : "descriptor.ovf",
      "hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/descriptor.ovf" ]
    }, {
      "name" : "descriptor.mf",
      "hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/descriptor.mf" ]
    }, {
      "etag" : "37"
      "name" : "vm-d5349476-aae2-4b65-bc9a-28effdc213fb-disk-0.vmdk",
      "hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/vm-d5349476-aae2-4b65-bc9a-28effdc213fb-disk-0.vmdk" ]
    } ],
    "properties" : {
    },
    "selfHref" : "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/item.json"
  }, {
    "version" : "2",
    "id" : "urn:uuid:b63c9bbe-3614-4153-82fd-d5f4916a1327",
    "name" : "template1",
    "created" : "2012-09-14T22:18:12.858Z",
    "description" : "Added with VMware OVFTool.",
    "type" : "vcsp.ovf",
    "files" : [ {
      "name" : "descriptor.ovf",
      "hrefs" : [ "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/file/descriptor.ovf" ]
    }, {
      "name" : "descriptor.mf",
      "hrefs" : [ "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/file/descriptor.mf" ]
    }, {
      "name" : "vm-3fe8a95b-ccd1-4816-b4ed-d631f3e2bbf3-disk-0.vmdk",
      "hrefs" : [ "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/file/vm-3fe8a95b-ccd1-4816-b4ed-d631f3e2bbf3-disk-0.vmdk" ]
    } ],
    "properties" : {
    },
    "selfHref" : "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/item.json"
  } ],
     "metadata" : [] 
     "vms" : [ {
      "name" : "vm1",
      "metadata" : [ ]
     
    }, {
      "name" : "vm2",
      "metadata" : []
    } ]
  }, {
  "version" : "10"
}

Metadata

The endpoint descriptor and endpoint index allow you to include object metadata that is used to create VMware Cloud Director object metadata when endpoint contents are synchronized by a subscribed catalog. For more information about the design and operation of VMware Cloud Director object metadata, see Working with Object Metadata.

metadata

An array of object metadata. You may include an arbitrary number of metadata objects in this array, subject to the size limitations documented in VMware Cloud Director API Object Metadata Limits

type: The type of the metadata value. One of STRING, BOOLEAN, DATETIME or NUMBER. See VMware Cloud Director API Object Metadata Contents.
domain: The access domain of the metadata. One of GENERAL or SYSTEM. See Access Control for VMware Cloud Director API Object Metadata. When VMware Cloud Director object metadata is created from this endpoint, the metadata domain is always set to SYSTEM, regardless of the value you supply here.
key: An arbitrary key name.
value: The value of the key.
visibility: The visibility the metadata. One of PRIVATE, READONLY or READWRITE. See Access Control for VMware Cloud Director API Object Metadata. When VMware Cloud Director object metadata is created from this catalog item, the metadata visibility is always set to READONLY, regardless of the value you supply here.

Item Descriptors

Every item listed in the endpoint index must include an item descriptor file in the directory that holds all the item's files. The contents, which must be expressed in JavaScript Object Notation (media type application/json) as defined by RFC4627, define a JSON object, and must specify values for the following key names.

version

An integer that specifies the version of the item, as described in Version Numbers.

id

The object identifier, expressed in URN format. This value uniquely identifies the catalog, persists for the life of the catalog, and must never be reused.

name

The display name of the catalog. Must be a nonempty string.

created

Time and date when the endpoint was created.

description

A description of the item, as it will appear in the destination catalog.

type

Item type. Must have one of the following values:

vcsp.iso if the item is an ISO image.
vcsp.ovf if the item is an OVF package.

files

An array of file objects that includes all the files that represent the item. Each file object is represented as an array with two elements:

name: The name of the file.
hrefs: An array of pathnames to the file. Must contain a single pathname to the file from the root of the endpoint, written as a URL fragment.

properties

An array of additional properties of the item. Must be empty.

The following example shows a typical item descriptor for an OVF package.

{
  "version" : "1",
  "id" : "urn:uuid:b63c9bbe-3614-4153-82fd-d5f4916a1327",
  "name" : "template1",
  "created" : "2012-09-14T22:18:12.858Z",
  "description" : "Added with VMware Ovf Tool.",
  "type" : "vcsp.ovf",
  "files" : [ {
    "name" : "descriptor.ovf",
    "size" : 9985,
    "hrefs" : [ "descriptor.ovf" ]
  }, {
    "name" : "vm-3fe8a95b-ccd1-4816-b4ed-d631f3e2bbf3-disk-0.vmdk",
    "size" : 833536,
    "hrefs" : [ "vm-3fe8a95b-ccd1-4816-b4ed-d631f3e2bbf3-disk-0.vmdk" ]
  } ],
  }  "properties" : {
  }
}

Responses

VCSP clients retrieve catalog files, including the descriptor and the endpoint index, with GET requests. The endpoint must return one of the following responses:

HTTP status 200 (OK) followed by the file content
HTTP status 503 (Service unavailable) followed by a document that provides additional information. This document has media type application/json, and provides values for the following keys:

status

Status of the requested file.

progress

File generation progress, expressed as an integer in the range 0 to 100.

message

An error message describing any errors that prevented the file from being generated.

The client continues to make GET requests until it receives either a 200 response or a 503 response with a nonempty message.

For example, an in-progress operation could return the following response.

{
  "status" : "",
  "progress" : 10
}

An operation that has encountered an error could return the following response.

{
  "status" : "failed",
  "message" : "File Generation failed"
}

Authentication

An endpoint can require authentication. VCSP clients always present the user name vcsp when logging in. The endpoint can specify any password for this user, but must accept the user name vcsp. The user name and password are encoded as specified for Basic HTTP authentication.

Version Numbers

Version numbers appear in the endpoint descriptor and endpoint index as version values, which are integer values that increment monotonically. It is the responsibility of the endpoint to increment the appropriate version value whenever any of the following changes occur.

Changes to a catalog item

A file in the item is added, removed, or changed.
The name or description of the item is changed.

Changes to a catalog

An item is added to or removed from the catalog.
The version value of any contained catalog item changes.
The name or description of the catalog is changed.