Home

Registering API Service Links

Where are my API extension REST methods?

So far we have looked at how API extensions work, how to register a new service extension, and what the messages look like that are sent from the API call to the AMQP exchange for our business logic to process.  However, if we were to go and do an http GET on an organization within our vCloud environment, we would not see anything special about that organization.  There would be no additional API calls (URLs) returned by the GET that would indicate we in fact have an API extension available to us that we can call against that organization.

What we can do is register custom links against entities within vCloud Director (vCD) environment that will be returned whenever we perform an http GET against that entity within vCD.  In this example we are registering against the organization entity type (application/vnd.vmware.vcloud.org+xml) but we can register links against any entity type we wish to add service links to.

Before we register our links, lets look at what an http GET looks like against our organization without any new API service links

Cloud wide vs entity specific links

When we register a service link with vCD, we can register the links with the entity type, which will add the links to all entities within our vCloud, or we can register them with specific URNs for the given entity type.  In simple terms, in context of our example we can add our links to all organizations within our vCloud, or to specific organizations within our vCloud by specifying the URNs of the organizations we want to register the links against in the XML that defines the links.

Defining a service link

In order to define our service link(s) we create an XML definition of the links we wish to register and post it to the /admin/extension/service vCloud REST method the exact same way we registered our service extension itself.  Nothing is different from the API interaction standpoint.  Only the XML is different.

If we look at a service link we want to register against our organization entity within vCD, we can from that easily define the XML that we require.

Desired link

https://<vCD-host>/api/org/<anyOrgId>/extstorage/iscsi/create

Service link XML definition

<vmext:LinkHref>
 {baseUri}org/{resourceId}/extstorage/iscsi/create
</vmext:LinkHref>

Breaking down the components of this XML snippet

{baseUri} will be replaced with the address of the vCD environment you're connecting to, or in our example case it translates to https://192.168.1.49/api.
{resourceId} will be replaced with the URN of the entity we are making the API call against, or in this case the URN of the organization we perform the API call against.

We need to specify more than simply the desired link.  vCD needs to know what entity type to register the link against, and optionally what URNs to register it against if it is not a vCloud wide link being registered.  This is an example of the ServiceLinks section of an API extension being registered to provide all of the calls we want for our external iSCSI as a Service implementation, to be registered against all the organizations within our vCloud.  We could have optionally specified the resourceId of the resource we wanted the links registered against.

    <vmext:ServiceLinks>
        <vmext:ServiceLink>
            <vmext:LinkHref>{baseUri}org/{resourceId}/extstorage/iscsi/create</vmext:LinkHref>
            <vmext:MimeType>application/xml</vmext:MimeType>
            <vmext:Rel>create</vmext:Rel>
            <vmext:ResourceType>application/vnd.vmware.vcloud.org+xml</vmext:ResourceType>
        </vmext:ServiceLink>
       
        <vmext:ServiceLink>
            <vmext:LinkHref>{baseUri}org/{resourceId}/extstorage/iscsi/delete</vmext:LinkHref>
            <vmext:MimeType>application/xml</vmext:MimeType>
            <vmext:Rel>delete</vmext:Rel>
            <vmext:ResourceType>application/vnd.vmware.vcloud.org+xml</vmext:ResourceType>
        </vmext:ServiceLink>       
       
        <vmext:ServiceLink>
            <vmext:LinkHref>{baseUri}org/{resourceId}/extstorage/iscsi/offline</vmext:LinkHref>
            <vmext:MimeType>application/xml</vmext:MimeType>
            <vmext:Rel>offline</vmext:Rel>
            <vmext:ResourceType>application/vnd.vmware.vcloud.org+xml</vmext:ResourceType>
        </vmext:ServiceLink>               

        <vmext:ServiceLink>
            <vmext:LinkHref>{baseUri}org/{resourceId}/extstorage/iscsi/online</vmext:LinkHref>
            <vmext:MimeType>application/xml</vmext:MimeType>
            <vmext:Rel>online</vmext:Rel>
            <vmext:ResourceType>application/vnd.vmware.vcloud.org+xml</vmext:ResourceType>
        </vmext:ServiceLink>       
       
        <vmext:ServiceLink>
            <vmext:LinkHref>{baseUri}org/{resourceId}/extstorage/iscsi/status</vmext:LinkHref>
            <vmext:MimeType>application/xml</vmext:MimeType>
            <vmext:Rel>status</vmext:Rel>
            <vmext:ResourceType>application/vnd.vmware.vcloud.org+xml</vmext:ResourceType>
        </vmext:ServiceLink>               
               
    </vmext:ServiceLinks>

Now after we register our service links against our organization, lets take a look at what an http GET against our organization looks like.

As you can see we now have new links we can call against our organization in order to interact with our storage as a service API extension.  This allows us to have whatever code (or person) is interacting with the API to automatically discover what methods are exposed by the organization for interacting with it.  We don't have to have prior knowledge of the methods to call, they are exposed by the organization.

Add comment


Security code
Refresh

Joomla templates by a4joomla