3.4 Adding API Links

Extending vCloud API with vCloud Extensibility Framework : Extension Example : 3.4 Adding API Links

While the new ticketing extension is registered, it does not show up in the link list. By using the ServiceLink object, you can add link elements to the representation of vCloud API objects. This can be done by passing the ServiceLinks with the original service extension registration, or it can be added later. In this case, they are added after the extension has been implemented.

When you view an organization:

# http --verify no --session=vcloud-gcp-admin --pretty colors GET https://vcd.gcp.local/api/org/<ORG_UUID>

there is no link element returned providing the path to the newly defined service. To add the new links, you must retrieve the UUID of the registered service:

# http --session=vcloud-gcp-admin --pretty colors GET https://vcd.gcp.local/api/admin/extension/service/query --verify no

This provides the list of all registered extensions. After finding the ticketing extension, you can get the details of the extension you added:

# http --verify no --session=vcloud-gcp-admin --pretty colors GET https://vcd.gcp.local/api/admin/extension/service/4c3eb8af-38ba-4ff9-8189-52329d601a58

One of the links that is returned allows you to add the ServiceLinks:

<vcloud:Link rel="add" href="https://vcd.gcp.local/api/admin/extension/service/4c3eb8af-38ba-4ff9-8189-52329d601a58/links" type="application/vnd.vmware.admin.serviceLink+xml"/>

POST this ServiceLink to this location. To build a ServiceLink, there are four required attributes:

• LinkHref – The value of the href attribute of this service Link. This can be any URI, and can include the variables {baseUri} and {resourceId}. When constructing the href value of the link, vCloud Director replaces {baseUri} with the vCloud Director REST API base URL, and replaces {resourceId} with the UUID portion of the id attribute value of the resource in which the link is inserted. The value must be less than or equal to 255 characters in length.

• MimeType – The value, specified as a MIME content type, of the type attribute of the link. The value must be less than or equal to 255 characters in length.

• Rel – The value of the rel attribute of the link. This value must be less than or equal to 255 characters in length.

• ResourceType – The object type, specified as a MIME content type, of the object in which the link appears. Must be less than or equal to 255 characters in length.

Example XML (https://github.com/johnnycuse/vcd-api-examples/blob/master/ticketing/ext-addLink.xml):

<?xml version="1.0" encoding="UTF-8"?>

<vmext:ServiceLink

xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5"

xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"

type="application/vnd.vmware.admin.serviceLink+xml">

<vmext:LinkHref>{baseUri}org/{resourceId}/ticketing</vmext:LinkHref>

<vmext:MimeType>application/vnd.example.vcd.tickets+xml</vmext:MimeType>

<vmext:Rel>listTickets</vmext:Rel>

<vmext:ResourceType>application/vnd.vmware.vcloud.org+xml</vmext:ResourceType>

</vmext:ServiceLink>

Add the link to the extension:

# http --verify no --session=vcloud-gcp-admin --pretty colors POST https://vcd.gcp.local/api/admin/extension/service/4c3eb8af-38ba-4ff9-8189-52329d601a58/links 'Content-type: application/vnd.vmware.admin.servicelink+xml' < ext-addLink.xml

After the link is added, call the org object to verify that it has been added:

# http --verify no --session=vcloud-gcp-admin --pretty colors GET https://vcd.gcp.local/api/org/<ORG_UUID>

The Org XML that is returned now includes the newly added ticketing link element: