Register an extension service to specify its namespace, AMQP exchange and routing key, and URL patterns. You can specify additional service properties during registration or update them later.

An extension service typically authenticates with the vCloud API as a system administrator, then registers itself with vCloud Director by POSTing a Service element to the system's .../api/admin/extension/service URL. A Service element must include the following elements.

Namespace

The service namespace, which must be unique among all registered extension services. Service namespace names that follow the naming convention used for Java packages (for example, com.example.service.backup) are more likely to be unique. If a service tries to register a namespace that is already registered with this vCloud Director installation, registration fails.

RoutingKey

The AMQP routing key that vCloud Director must use when routing messages to the service.

Exchange

The AMQP exchange name that vCloud Director must use when routing messages to the service. The service must create the specified exchange on the AMQP service that vCloud Director uses. The exchange type must be direct.

ApiFilters

Specifies one or more URL patterns that the vCloud Director REST service must treat as extension requests. URL patterns can include regular expressions that java.util.regex.Pattern recognizes. See Create an API Filter for an Extension Service.

Registration can also specify the following optional properties:

■

Definitions of Link elements that the service adds to the representations of vCloud API objects. See Service-Specific Links.

■

Authorization framework for controlling access to the service's objects and operations. See Authorization Framework for Extension Service Operations.

■

Locations of schema files if the service provides its own API. See REST APIs for Extension Services

You can also create or update these properties after you register the service.

Prerequisites

This operation is restricted to system administrators.

Procedure
1

Retrieve the XML representation of the cloud.

Use a request like this one: 

GET https://vcloud.example.com/api/admin/extension
2

Examine the response to find the Link for adding extension services.

This URL is present in the VMWExtension element, and has the following form. 

<vcloud:Link
   rel="down"
   type="application/vnd.vmware.admin.extensionServices+xml"
   href="https://vcloud.example.com/api/admin/extension/service"/>
3

Construct a Service element.

See the request portion of Example: Register an Extension Service.

4

POST the Service element to the URL described in Step 2.

See the request portion of Example: Register an Extension Service.

Example: Register an Extension Service

This request registers an extension service named SDK-BackupExtension. The request specifies the service namespace and routing key, and several URL patterns to be used as API filters. Messages for the service are sent to the AMQP exchange named sdkext with routing key sdkbackup.

Note

If the specified exchange does not exist on the AMQP service that vCloud Director uses, an internal server error occurs whenever vCloud Director receives a request that matches one of the service's API filters.

This request also includes several ServiceLink elements. For information about the contents of these elements, see Service-Specific Links.

Request: 

POST https://vcloud.example.com/api/admin/extension/service
Content Type: application/vnd.vmware.admin.service+xml
<?xml version="1.0" encoding="UTF-8"?>
<vmext:Service
   xmlns="http://www.vmware.com/vcloud/v1.5"
   xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5"
   name="SDK-BackupExtension">
   <vmext:Namespace>org.example.vcd.backup</vmext:Namespace>
   <vmext:Enabled>true</vmext:Enabled>
   <vmext:AuthorizationEnabled>true</vmext:AuthorizationEnabled>
   <vmext:RoutingKey>backup</vmext:RoutingKey>
   <vmext:Priority>50</vmext:Priority>
   <vmext:Exchange>sdkext</vmext:Exchange>
   <vmext:ApiFilters>
      <vmext:ApiFilter>
         <vmext:UrlPattern>(/api/org/.*/backups)|(/api/vApp/vapp-.*/backups)|(/api/vApp/vapp-.*/action/backup)|(/api/backup/.*)</vmext:UrlPattern>
      </vmext:ApiFilter>
   </vmext:ApiFilters>
   <vmext:ServiceLinks>
      <vmext:ServiceLink>
         <vmext:LinkHref>{baseUri}org/{resourceId}</vmext:LinkHref>
         <vmext:MimeType>application/vnd.example.vcd-backup.backupList+xml</vmext:MimeType>
         <vmext:Rel>down</vmext:Rel>
         <vmext:ResourceType>application/vnd.example.vcd-backup.org+xml</vmext:ResourceType>
      </vmext:ServiceLink>
      <vmext:ServiceLink>
         <vmext:LinkHref>{baseUri}api/vApp/vapp-{resourceId}/backups</vmext:LinkHref>
         <vmext:MimeType>application/vnd.example.vcd-backup.backupList+xml</vmext:MimeType>
         <vmext:Rel>down</vmext:Rel>
         <vmext:ResourceType>application/vnd.example.vcd-backup.vApp+xml</vmext:ResourceType>
      </vmext:ServiceLink>
      <vmext:ServiceLink>
         <vmext:LinkHref>{baseUri}vApp/vapp-{resourceId}/action/backup</vmext:LinkHref>
         <vmext:MimeType>application/vnd.example.vcd-backup.createBackupParams+xml</vmext:MimeType>
         <vmext:Rel>backup</vmext:Rel>
         <vmext:ResourceType>application/vnd.example.vcd-backup.vApp+xml</vmext:ResourceType>
      </vmext:ServiceLink>
   </vmext:ServiceLinks>
</vmext:Service>

The server registers the service and returns a Service element that includes information derived from the contents you POSTed, and a set of Link elements that you can use to access, remove, disable, or modify the extension service.

Response: 

201 Created
Content Type: application/vnd.vmware.admin.service+xml
...
<vmext:Service
   xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5"
   xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"
   name="SDK-BackupExtension"
   id="urn:vcloud:externalService:45"
   type="application/vnd.vmware.admin.service+xml"
   href="https://vcloud.example.com/api/admin/extension/service/45"
   ... >
   <vcloud:Link
      rel="remove"
      href="https://vcloud.example.com/api/admin/extension/service/45" />
   <vcloud:Link
      rel="edit"
      type="application/vnd.vmware.admin.service+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45" />
   <vcloud:Link
      rel="rights"
      type="application/vnd.vmware.admin.rights+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/rights" />
   <vcloud:Link
      rel="down:serviceLinks"
      type="application/vnd.vmware.vcloud.query.records+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/links" />
   <vcloud:Link
      rel="bundle:upload"
      type="application/vnd.vmware.admin.bundleUploadParams+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/localizationbundles" />
   <vcloud:Link
      rel="add"
      type="application/vnd.vmware.admin.serviceLink+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/links" />
   <vcloud:Link
      rel="down:apiFilters"
      type="application/vnd.vmware.vcloud.query.records+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/apifilters" />
   <vcloud:Link
      rel="add"
      type="application/vnd.vmware.admin.apiFilter+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/apifilters" />
   <vcloud:Link
      rel="add"
      type="application/vnd.vmware.admin.apiDefinition+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/apidefinitions" />
   <vcloud:Link
      rel="down:apiDefinitions"
      type="application/vnd.vmware.vcloud.query.records+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/apidefinitions" />
   <vcloud:Link
      rel="add"
      type="application/vnd.vmware.admin.resourceClass+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/resourceclasses" />
   <vcloud:Link
      rel="down:resourceClasses"
      type="application/vnd.vmware.vcloud.query.records+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/resourceclasses" />
   <vcloud:Link
      rel="authorization:check"
      type="application/vnd.vmware.admin.authorizationCheckParams+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/authorizationcheck" />
   ...
</vmext:Service>

The following elements are never returned as part of a response body. Instead, they are returned as Link elements in the body of their container.

■

AclRules

■

ApiDefinitions and Files

■

ApiFilters

■

ResourceClassActions

■

ResourceClasses

■

ServiceLinks

■

ServiceResources

For example, to retrieve the contents of the ServiceLinks element POSTed with the request body in this example, GET the URL in this Link: 

<vcloud:Link
      rel="down:serviceLinks"
      type="application/vnd.vmware.vcloud.query.records+xml"
      href="https://vcloud.example.com/api/admin/extension/service/45/links" />