Operations with Links

APS resources can be linked with each other basing on the relationship defined in the respective APS types. Link management is considered here in details.

Overview

The relations section in an APS type specifies an APS type or the resources that can be linked and two relation attributes, collection (singular or collection) and required (weak or strong), that can affect the process of establishing and deleting links between APS resources. In addition, it is possible to set a link between a resource with a declared (named) relation and a resource without a corresponding declared backward relation (anonymous backward relation).

Each link has the following properties within an APS resource representation:

Property	Type	Description
<name>	string	The name of a link defined in Relations definition.
aps.link	string	The kind of a link. The following values are supported: strong - the resource cannot exist without the linked resource weak - the resource is aware of the linked resource collection - declares that the resource is linked to a collection of resources
aps.id	string	The ID of the linked resource - only available when a relation is singular, that is NOT a collection
aps.href	URI	The URI of the linked resource; in case of collection, it refers to the collection of resources

Example of a singular link:

"server": {
    "aps": {
       "link": "strong",
       "id": "b8da1007-3c7c-4d6e-94c8-480a2df3d732",
       "href": "/aps/2/resources/b8da1007-3c7c-4d6e-94c8-480a2df3d732"
    }
}

Example of a collection link:

"containers": {
    "aps": {
       "link": "collection",
       "href": "/aps/2/resources/b8da1007-3c7c-4d6e-94c8-480a2df3d732/containers"
    }
}

Possible combinations of linked resources used in practice are collected in the following table.

Resource1	Resource2	Schema	Description
weak singular	weak singular		- Resources can exist without a link between them. - Link can be set or deleted when both resources exist.
weak singular	strong singular		- Resource2 cannot exist without a link. - When creating resource2, the link must be created.
weak collection	weak singular		- Resources can exist without a link between them. - Link can be set or deleted when both resources exist. - Resource1 may have multiple links based on the same relation.
Weak collection	Strong singular		- Resource2 cannot exist without a link. - When creating resource2, the link must be created. - Resource1 may have multiple links based on the same relation.
Strong collection	Weak singular		- Resource1 cannot exist with the empty link collection. - When the last link of the collection is deleted, Resource1 is deleted as well.
Anonymous	Weak singular		- Resources can exist without a link between them. - Link can be set or deleted when both resources exist. - Notifications about link operations are not sent to resource1. - Resource1 may have multiple anonymous links.
Anonymous	Strong singular		- Resource2 cannot exist without a link. - When creating resource2, the link must be created. - Notifications about link operations are not sent to resource1. - Resource1 may have multiple anonymous links.

Note

When there is a request for deleting a resource, the resource links will be deleted beforehand.

This document contains the following sections.

• Link Management - general aspects of link management

• Getting Linked Resources - getting link collections and linked resources

• Linking Resources - linking resources to each other

• Unlinking Resources - removing links between resources

• Relinking Resources - relinking a resource from one neighbor to another

• Provisioning Resources with Required Links - using link operations for provisioning resources

Link Management

There are the following actors in a link operation:

• An initiator of the operation, for example, UI script or an application.

• APS controller.

• One or two applications. When a link connects resources from different applications, the APS controller communicates with both applications.

A link operation contains the following steps:

1. An initiator sends a request for link operation to the APS controller.

2. The APS controller processes the requested operation internally.

3. Once it is processed, the APS controller must notify the application endpoint (or the two endpoints) about it. Notifications are sent by means of REST requests.

4. The APS controller gets response from each involved endpoint.

5. The APS controller returns its own response to the initiator of the operation.

Every relation defined in a Type Definition corresponds to the following URI within a resource instance: /aps/resources/{ID}/{relation}, where {ID} is a resource identifier and {relation} is a relation name.

The examples in this section will be based on the following resource schema with slight modifications in different examples.

To implement the schema, the vps resource type declares the following relations:

{
  "apsVersion": "2.0",
  "name": "vps",
  "id": "http://aps-standard.org/samples/vpsclouds/vpses/1.0",
  ...
  "relations": {
    "context": {
      "type": "http://aps-standard.org/samples/vpsclouds/contexts/1.0",
      "required": true,
      "collection": false
    },
    "offer": {
      "type": "http://aps-standard.org/samples/vpsclouds/offers/1.0",
      "required": true,
      "collection": false
    },
    "user": {
      "type": "http://aps-standard.org/types/core/service-user/1.0",
      "required": true,
      "collection": false
    }
  }
}

In accordance with this declaration, there are three named strong singular link collections (URIs) addressed to the APS controller for managing links of a certain VPS, whose ID is {vps-id}:

• /aps/2/resources/{vps-id}/context

• /aps/2/resources/{vps-id}/offer

• /aps/2/resources/{vps-id}/user

Each application exposes an endpoint for processing link operations. The REST collection /{service-id}/{resource-id}/{relation-name} is used to notify the service {service-id} about linking or unlinking the resource, represented by its {resource-id}, through the {relation-name}. For example, if a VPS ID is cbb1ad63-c42b-418f-b1fb-e9ed94f5ce56 and its resource factory (service) is vpses, the APS controller will notify the VPS resource about link operations through the following link collections:

• /vpses/cbb1ad63-c42b-418f-b1fb-e9ed94f5ce56/context/

• /vpses/cbb1ad63-c42b-418f-b1fb-e9ed94f5ce56/offer/

• /vpses/cbb1ad63-c42b-418f-b1fb-e9ed94f5ce56/user/

In this document, to address the two ends of a link, let us use the following terms:

• Local end of a link is the link end on the resource, whose ID receives a request for the link operation. In each collection of the above list, the local end is bound to the VPS.

• Remote end of a link is the other end of the link, opposite to the local end. In the first sample collection of the above list, it will be the end bound to the context resource.

Besides the named relation collections as mentioned above, the APS controller can also work with the generic collection aps/links. It can be used for operating any links of a certain resource regardless of their collection name. It means, in some cases, instead of addressing one of three mentioned above collections, it is possible to send a request to the generic collection as follows:

/vpses/cbb1ad63-c42b-418f-b1fb-e9ed94f5ce56/aps/links/

Getting Linked Resources

APS controller allows the following GET operations over resource links.

• Getting a list of all links of a certain resource. To get the list for resource {id1}, run:

  GET /aps/2/resources/{id1}/aps/links
  

  This request adds some capabilities for developers:

  • The response list contains also anonymous links, whose names are empty, that is “name”: “”.

  • If a remote resource is linked via a named relation, in response it is presented by the backrel attribute.

  The response for an account’s links may look as follows:

  [
      {
         "name": "subscriptions",
         "link": "weak",
         "id": "18f93665-7e45-40a1-bf9c-b547a26b9ede",
         "href": "/aps/2/resources/18f93665-7e45-40a1-bf9c-b547a26b9ede",
         "type": "http://parallels.com/aps/types/pa/subscription/1.0",
         "backrel": "account"
      },
      ...
  ]
  

  This response shows that the subscriptions collection of the specified account is linked with a subscription whose backward relation is called account.

• Getting all resources bound to a link collection. To list all resources in the {id1}/{relation} collection, run:

  GET /aps/2/resources/{id1}/{relation}
  

• Getting properties of a linked resource. To get properties of resource {id2} linked to collection {id1}/{relation}, run:

  GET /aps/2/resources/{id1}/{relation}/{id2}
  

  Note

  The result is the same as in a case of direct access to resource {id2}. Actually the APS controller redirects the request to /aps/2/resources/{id2} with code HTTP/1.1 301 Moved Permanently and finally returns code HTTP/1.1 200 OK.

The following example illustrates how to get a full list of all links of a user.

Request:

GET aps/2/resources/5f4ef5a5-c9e5-44cf-a862-ea421b7c5534/aps/links

In response, there are two anonymous links with empty names and a link of a named collection organization:

HTTP/1.1 200 OK

[
   {
      "name": "organization",
      "link": "strong",
      "id": "d9170696-aacf-4e41-9f88-d3be5c0a909c",
      "href": "/aps/2/resources/d9170696-aacf-4e41-9f88-d3be5c0a909c",
      "type": "http://parallels.com/aps/types/pa/account/1.0",
      "backrel": "users"
   },
   {
      "name": "",
      "link": "weak",
      "id": "32310cf1-1096-4801-b2b6-28b81f460af7",
      "href": "/aps/2/resources/32310cf1-1096-4801-b2b6-28b81f460af7",
      "type": "http://aps-standard.org/samples/suwizard1p/vps/1.0",
      "backrel": "user"
   },
   {
      "name": "",
      "link": "weak",
      "id": "eaecd4bd-fae7-4cfa-ba84-37bb4e7d50b3",
      "href": "/aps/2/resources/eaecd4bd-fae7-4cfa-ba84-37bb4e7d50b3",
      "type": "http://aps-standard.org/samples/suwizard1p/vps/1.0",
      "backrel": "user"
      }
]

The following example illustrates how to get a list of VPSes linked to a certain offer.

Request:

GET /aps/2/resources/4dada30e-6805-4db3-b149-2e60b5f3f62c/vpses

Response:

HTTP/1.1 200 OK

[
   {
      "aps":
      {
         "type": "http://aps-standard.org/samples/vpsclouds/vpses/1.0",
         "id": "4f2e7744-d25a-47d4-86c7-0ba6db71a780",
         "status": "aps:ready",
         "revision": 3,
         "modified": "2014-03-04T13:57:48Z"
      },
      "cpuusage":
      {
         "limit": null,
         "usage": null
      },
      "description": "",
      "diskusage":
      {
         "limit": null,
         "usage": null
      },
      "hardware":
      {
         "CPU":
         {
            "number": 1
         },
         "diskspace": 8,
         "memory": 256
      },
      "memoryusage":
      {
         "limit": null,
         "usage": null
      },
      "name": "vps-202",
      "platform":
      {
         "OS":
         {
            "name": "centos6",
            "version": null
         },
         "arch": null
      },
      "state": "Stopped",
      "userName": "George Harrison"
   },
   {
      "aps":
      {
         "type": "http://aps-standard.org/samples/vpsclouds/vpses/1.0",
         "id": "d87b8299-b4c0-4aab-8724-a39bcfd6ba01",
         "status": "aps:ready",
         "revision": 3,
         "modified": "2014-03-04T09:04:10Z"
      },
      "cpuusage":
      {
         "limit": null,
         "usage": null
      },
      "description": "",
      "diskusage":
      {
         "limit": null,
         "usage": null
      },
      "hardware":
      {
         "CPU":
         {
            "number": 1
         },
         "diskspace": 8,
         "memory": 256
      },
      "memoryusage":
      {
         "limit": null,
         "usage": null
      },
      "name": "vps-201",
      "platform":
      {
         "OS":
         {
            "name": "centos6",
            "version": null
         },
         "arch": null
      },
      "state": "Stopped",
      "userName": "Mary Jons"
   }
]

Requesting properties of the offer bound to the VPS link offer (all request parameters in URI):

GET /aps/2/resources/d87b8299-b4c0-4aab-8724-a39bcfd6ba01/offer/4dada30e-6805-4db3-b149-2e60b5f3f62c

In response, the full resource presentation is returned, including its links:

HTTP/1.1 200 OK

{
   "aps":
   {
      "type": "http://aps-standard.org/samples/vpsclouds/offers/1.0",
      "id": "4dada30e-6805-4db3-b149-2e60b5f3f62c",
      "status": "aps:ready",
      "revision": 3,
      "modified": "2014-03-04T09:00:10Z",
      "schema": "/aps/2/types/83",
      "package":
      {
         "id": "dce3b1d1-1485-4892-ad2d-0ca2218836e5",
         "href": "/aps/2/packages/dce3b1d1-1485-4892-ad2d-0ca2218836e5"
      }
   },
   "hardware":
   {
      "CPU":
      {
         "number": 4
      },
      "diskspace": 32,
      "memory": 512
   },
   "offerdscr": null,
   "offername": "Test Silver",
   "platform":
   {
      "OS":
      {
         "name": "centos6",
         "version": null
      },
      "arch": null
   },
   "cloud":
   {
      "aps":
      {
         "link": "strong",
         "href": "/aps/2/resources/0121aaf7-9015-4d89-9bc8-fc89b9204f63",
         "id": "0121aaf7-9015-4d89-9bc8-fc89b9204f63"
      }
   },
   "vpses":
   {
      "aps":
      {
         "link": "collection",
         "href": "/aps/2/resources/4dada30e-6805-4db3-b149-2e60b5f3f62c/vpses"
      }
   }
}

Linking Resources

Operations

Creation of a link for a pair of existing resources is started by sending a POST request to the corresponding collection of one of resources. Such a scenario can be based on the following two cases when both resources can exist without a link between them:

• The corresponding relations on both ends are weak.

• The relation is weak on the local end and is not declared at all on the remote end (anonymous).

The following example illustrates the first case. A VPS can be configured basing on predefined configuration of an offer, or can be configured without an offer. Therefore, the vps schema declares a weak singular relation with an offer.

Note

For generalization only, hereafter, let us suppose that the related resources are available on different endpoints.

To establish a link, the APS controller must receive a POST request addressed to the proper resource collection. In the request body, the paired resource ID must be specified. The backrel attribute, if used, explicitly specifies the remote relation. Once the operation is processed internally, the APS controller sends POST requests to both related link collections on the application endpoints, as illustrated here:

In the above diagram, the APS controller sends two requests subsequently.

1. POST request to the remote end, that is to /offers/{offer-id}/vpses.

2. POST request to the local end, that is to /vpses/{vps-id}/offer.

In case of success the APS controller returns the presentation of the paired resource containing presentation of the remote end of the link.

Resolving Backward Relationship

In a case the backrel property is not specified in a request, the APS controller will attempt to figure out the backward link if the remote resource has any declared relationship. If there is a remote relation allowing a connection with an APS type that the local resource is implementing, the APS controller will create a backward link on that relation and return its name as the backrel property. If the APS controller fails to find such a relation the remote end of the new link will be anonymous.

In some cases, the automatic assignment of the backward link is undesirable. For example, if the remote resource has a relationship collection that allows connection with resources implementing the APS core resource type, that collection will always match the above mentioned auto-assignment algorithm. To avoid such case, follow these recommendations:

• If not absolutely necessary, in the declaration of a relationship collection, avoid the use of an APS type, which is pretty high in the APS type hierarchy and thus is implemented by many other APS types.

• Wherever possible, declare the mutual relationship on both ends, that is in both APS types whose resources must be or can be linked.

Note

In a case of using anonymous relation on the remote end, the APS controller will send a POST request only to the named collection on the local end.

APS Controller Interface

In the POST request addressed to a resource collection, the only mandatory attribute in its body is the ID of the paired resource. The backrel attribute is optional. It specifies the collection name on the paired resource (remote end).

POST /aps/2/resources/{id1}/{relation}

 {
     "aps" : {
         "id" : "{id2}",
         "backrel" : "{back-relation}"
     }
     ...
 }

If the backrel attribute is missed, the APS controller will try to figure out the remote end. If there is ambiguity, that is not possible to figure out the remote named relation, the operation will fail.

The following are sample REST messages exchanged between the operation initiator and the APS controller.

APS controller receives a request for creating a link between the VPS (its ID in the URI) and the offer (its ID in the body):

POST /aps/2/resources/d87b8299-b4c0-4aab-8724-a39bcfd6ba01/offer/

{
"aps":{
          "id": "4dada30e-6805-4db3-b149-2e60b5f3f62c",
         "backrel": "vpses"
}
}

Response:

HTTP/1.1 200 OK

{
   "aps":
   {
      "type": "http://aps-standard.org/samples/vpsclouds/offers/1.0",
      "id": "4dada30e-6805-4db3-b149-2e60b5f3f62c",
      "status": "aps:ready",
      "revision": 3,
      "modified": "2014-03-04T09:00:10Z",
      "package":
      {
         "id": "dce3b1d1-1485-4892-ad2d-0ca2218836e5",
         "href": "/aps/2/packages/dce3b1d1-1485-4892-ad2d-0ca2218836e5"
      }
   },
   "hardware":
   {
      "CPU":
      {
         "number": 4
      },
      "diskspace": 32,
      "memory": 512
   },
   "offername": "Test Silver",
   "platform":
   {
      "OS":
      {
         "name": "centos6"
      }
   },
   "cloud":
   {
      "aps":
      {
         "link": "strong",
         "href": "/aps/2/resources/0121aaf7-9015-4d89-9bc8-fc89b9204f63",
         "id": "0121aaf7-9015-4d89-9bc8-fc89b9204f63"
      }
   },
   "vpses":
   {
      "aps":
      {
         "link": "collection",
         "href": "/aps/2/resources/4dada30e-6805-4db3-b149-2e60b5f3f62c/vpses"
      }
   }
}

Warning

Linking the same pair of resources more than one time is prohibited.

Endpoint Interface

Application endpoints receive notifications about operations with named link collections.

A notification of creating a link between the offer (its ID and collection is in the URI) and the VPS (its ID and collection is in the body) looks as follows:

POST /vpstest/offers/4dada30e-6805-4db3-b149-2e60b5f3f62c/vpses

{
        "aps":
        {
                "type": "http://aps-standard.org/samples/vpsclouds/vpses/1.0",
                "id": "d87b8299-b4c0-4aab-8724-a39bcfd6ba01",
                "status": "aps:ready",
                "revision": 3,
                "modified": "2014-03-04T09:04:10Z",
                "package":
                {
                        "id": "dce3b1d1-1485-4892-ad2d-0ca2218836e5",
                        "href": "/aps/2/packages/dce3b1d1-1485-4892-ad2d-0ca2218836e5"
                }
        },
        "description": "",
        "hardware":
        {
                "CPU":
                {
                        "number": 1
                },
                "diskspace": 8,
                "memory": 256
        },
        "name": "vps-101",
        "platform":
        {
                "OS":
                {
                        "name": "centos6"
                }
        },
        "state": "Stopped",
        "userName": "Mary Jons",
        "context":
        {
                "aps":
                {
                        "link": "strong",
                        "href": "/aps/2/resources/15478a74-dce2-4d76-9c0a-4b18f4725b1c",
                        "id": "15478a74-dce2-4d76-9c0a-4b18f4725b1c"
                }
        },
        "offer":
        {
                "aps":
                {
                        "link": "weak",
                        "href": "/aps/2/resources/4dada30e-6805-4db3-b149-2e60b5f3f62c",
                        "id": "4dada30e-6805-4db3-b149-2e60b5f3f62c"
                }
        },
        "user":
        {
                "aps":
                {
                        "link": "strong",
                        "href": "/aps/2/resources/5f4ef5a5-c9e5-44cf-a862-ea421b7c5534",
                        "id": "5f4ef5a5-c9e5-44cf-a862-ea421b7c5534"
                }
        }
}

The response on success looks as follows:

HTTP/1.1 200 OK

Unlinking Resources

Operations

To start deleting a link between a pair of existing resources, the APS controller must receive a DELETE request addressed to the corresponding collection of one of the resources.

A DELETE request to /aps/2/resources/{id1}/{relation}/{id2} removes a link between resources {id1} and {id2} on the {id1}/{relation} collection.

The following cases should be considered:

• If the link is based on weak named relations on both ends, just the link will be deleted. Once the DELETE operation is processed internally, the APS controller sends two DELETE notifications, each to the appropriate named collection.

• If the local end of the link ({id1}/{relation}/) is weak and remote end is anonymous, then the APS controller will send only one DELETE notification addressed to the named weak collection.

• If the local end of the link ({id1}/{relation}/) is strong, the operation will fail, since resource {id1} cannot exist without the link.

• If the remote end of the link (the end on resource {id2}) is strong, then the APS controller will delete resource {id2} along with removal of the link.

  Note

  If resource {id2} has links with other resources, the APS controller must delete those links before the resource is deleted. It means, in some cases, a link operation can launch a long chain of other operations with resources and their links.

The following scenario illustrates a case when both resources can exist without a link between them, that is a weak relation is declared on both ends - vps and offer.

APS Controller Interface

In the following example, a link between a VPS (its collection is in the URI) and an offer (its ID is in the URI) is removed.

Request:

DELETE /aps/2/resources/d87b8299-b4c0-4aab-8724-a39bcfd6ba01/offer/4dada30e-6805-4db3-b149-2e60b5f3f62c

Response:

HTTP/1.1 204 No Content

It is possible to use the generic link interface. Issuing a DELETE request to /aps/2/resources/{id1}/aps/links/{id2} removes a link with “weak” ends. If the local end is “strong”, then an error is returned. If the other end is “strong”, then the dependent resource is removed with its “strong” link too.

Sample request:

DELETE /aps/2/resources/7389d901-701a-4ada-bac1-50b5443b3fa5/aps/links/b8da1007-3c7c-4d6e-94c8-480a2df3d732

Sample response:

HTTP/1.1 200 OK

Endpoint Interface

An example of a DELETE operation for a link between a VPS (its collection is in the URI) and an offer (its ID is in the URI) on the VPS side is presented below.

Request:

DELETE /vpstest/vpses/d87b8299-b4c0-4aab-8724-a39bcfd6ba01/offer/4dada30e-6805-4db3-b149-2e60b5f3f62c

Response:

HTTP/1.1 204 No Content

Relinking Resources

Operations

Relink operation combines two types of link operations - delete and create. If {relation} of resource {id1} is singular and the resource is already linked with another resource through this relation, the APS controller must delete the link on the remote end of the current link first, and then create the new link.

In the following example, VPS-101 is linked with the Silver offer and it is necessary to relink the VPS to the Gold offer.

The operation is started the same way as if a link creation is requested. On receiving the POST request, the APS controller will delete the existing link and then create the new one. Accordingly, it will notify the application endpoint about it.

APS Controller Interface

REST messages are the same as considered in the Linking Operation section, for example:

POST /aps/2/resources/01c6ab47-9715-430d-817e-89eff8c3112f/offer/

{
   "aps":{
            "id": "9a08d512-2ce1-491d-9bdc-b81553782985",
   }
}

Sample response:

HTTP/1.1 200 OK

{
   "aps":
   {
      "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/offers/1.0",
      "id": "9a08d512-2ce1-491d-9bdc-b81553782985",
      "status": "aps:ready",
      "revision": 3,
      "modified": "2014-03-03T15:43:32Z",
      "package":
      {
         "id": "d3ad0a6b-69f1-476f-8aba-cfa72c385978",
         "href": "/aps/2/packages/d3ad0a6b-69f1-476f-8aba-cfa72c385978"
      }
   },
   "hardware":
   {
      "CPU":
      {
         "number": 8
      },
      "diskspace": 50,
      "memory": 1024
   },
   "offername": "Gold",
   "platform":
   {
      "OS":
      {
         "name": "debian"
      }
   },
   "cloud":
   {
      "aps":
      {
         "link": "strong",
         "href": "/aps/2/resources/d4ab3c1a-b33f-4d65-bc9e-d240e309bf28",
         "id": "d4ab3c1a-b33f-4d65-bc9e-d240e309bf28"
      }
   },
   "vpses":
   {
      "aps":
      {
         "link": "collection",
         "href": "/aps/2/resources/9a08d512-2ce1-491d-9bdc-b81553782985/vpses"
      }
   }
}

Endpoint Interface

When relinking a resource, the APS controller sends two types of notifications, one - about deleting the existing link on the remote end as in the Unlinking Resources section, and the others - about creation of a new link as in the Linking Resources section.

Provisioning Resources with Required Links

Operations

By means of a link creation operation it is possible to create a linked resource. If an existing resource {id1} has a link collection {relation}, the REST request for creating a resource of type {type2} linked to {id1}/{relation} looks as:

POST /aps/2/resources/{id1}/{relation}

{"aps": {
   "type": "{type2}"},
   ..."resource properties": "and their values",...
}

As a result, the APSC controller and the application must provision the required resource and bind it to the {id1}/{relation} collection.

The following example is based on the sample diagram where a VPS must have three strong links, including two named links and one link with a service user that does not have a named backward relation. The POST request with required VPS properties is sent to the vpses collection of the Silver offer.

Once the POST request is processed internally, the APS controller sends to the application endpoint:

• Two notifications about creation of named links with the management context and an offer

• POST request for creating the VPS along with a link to a service user

APS Controller Interface

APS controller receives a REST request with all necessary data to create a resource and bind it to an existing resource. If the new resource must also have other links with different resources, the best way is to specify them in the body. If a link for a strong relation is not specified in the body, the APS controller will try to create a link with a proper resource on the remote end.

The request below contains the following data.

• URI specifies a link collection of a management context.

• Request body contains:

  • VPS properties

  • VPS link to an offer

For demo purposes, the body does not contain a VPS link to a user. This must be figured out by the APS controller.

POST /aps/2//resources/9284f8d3-8ad7-4327-948c-22f780a18fa6/vpses

{
   "aps":{"type":"http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0"},
   "name":"vps-222",
   "hardware":{"CPU":{"number":"4"},"diskspace":"32","memory":"512"},
   "platform":{"OS":{"name":"centos6"}},
   "offer":{
      "aps":{
         "link": "strong","href": "/aps/2/resources/01a1ecd0-0911-450a-b0a7-a37daf8129fc",
         "id": "01a1ecd0-0911-450a-b0a7-a37daf8129fc"
}}}

In response, the APS controller returns the full representation of the new VPS, as required, along with a strong link to a discovered user:

HTTP/1.1 200 OK

{
        "aps":
        {
                "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0",
                "id": "248c9623-55ef-4856-943c-ecd8c4eb05bf",
                "status": "aps:ready",
                "revision": 3,
                "modified": "1927-03-02T06:43:36Z",
                "package":
                {
                        "id": "d3ad0a6b-69f1-476f-8aba-cfa72c385978",
                        "href": "/aps/2/packages/d3ad0a6b-69f1-476f-8aba-cfa72c385978"
                }
        },
        "name": "vps-222",
        "hardware":
        {
                "CPU":
                {
                        "number": 4
                },
                "diskspace": 32,
                "memory": 512
        },
        "platform":
        {
                "OS":
                {
                        "name": "centos6"
                }
        },
        "context":
        {
                "aps":
                {
                        "link": "strong",
                        "href": "/aps/2/resources/9284f8d3-8ad7-4327-948c-22f780a18fa6",
                        "id": "9284f8d3-8ad7-4327-948c-22f780a18fa6"
                }
        },
        "offer":
        {
                "aps":
                {
                        "link": "strong",
                        "href": "/aps/2/resources/01a1ecd0-0911-450a-b0a7-a37daf8129fc",
                        "id": "01a1ecd0-0911-450a-b0a7-a37daf8129fc"
                }
        },
        "user":
        {
                "aps":
                {
                        "link": "strong",
                        "href": "/aps/2/resources/5888680c-19a9-4e92-b95e-d241c64a8c66",
                        "id": "5888680c-19a9-4e92-b95e-d241c64a8c66"
                }
        }
}

Endpoint Interface

Depending on the complexity of the resource schema, the APS controller can generate a chain of operations, such as:

• Creating links for all declared strong relations

• Possibly creating resources if there are no proper resources for strong relations

• At last, creating the requested resource

The following are two notifications and one request for creating the VPS as presented earlier in the sequence diagram.

1. Linking the new VPS with the management context collection:

   POST /vpscloud/contexts/9284f8d3-8ad7-4327-948c-22f780a18fa6/vpses
   
   {      "aps":
           {
                   "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0",
                   "id": "248c9623-55ef-4856-943c-ecd8c4eb05bf",
                   "status": "aps:provisioning",
                   "revision": 3,
                   "modified": "1927-03-02T06:43:36Z",
                   "package":
                   {
                           "id": "d3ad0a6b-69f1-476f-8aba-cfa72c385978",
                           "href": "/aps/2/packages/d3ad0a6b-69f1-476f-8aba-cfa72c385978"
                   }
           },
           "hardware":
           {
                   "CPU":
                   {
                           "number": 4
                   },
                   "diskspace": 32,
                   "memory": 512
           },
           "name": "vps-222",
           "platform":
           {
                   "OS":
                   {
                           "name": "centos6"
                   }
           },
           "context":
           {
                   "aps":
                   {
                           "link": "strong",
                           "href": "/aps/2/resources/9284f8d3-8ad7-4327-948c-22f780a18fa6",
                           "id": "9284f8d3-8ad7-4327-948c-22f780a18fa6"
                   }
           }
   }
   

   Response:

   HTTP/1.1 200 OK
   

2. Linking the new VPS with the offer collection:

   POST /vpscloud/offers/01a1ecd0-0911-450a-b0a7-a37daf8129fc/vpses
   
   {
           "aps":
           {
                   "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0",
                   "id": "248c9623-55ef-4856-943c-ecd8c4eb05bf",
                   "status": "aps:provisioning",
                   "revision": 3,
                   "modified": "1927-03-02T06:43:36Z",
                   "package":
                   {
                           "id": "d3ad0a6b-69f1-476f-8aba-cfa72c385978",
                           "href": "/aps/2/packages/d3ad0a6b-69f1-476f-8aba-cfa72c385978"
                   }
           },
           "hardware":
           {
                   "CPU":
                   {
                           "number": 4
                   },
                   "diskspace": 32,
                   "memory": 512
           },
           "name": "vps-222",
           "platform":
           {
                   "OS":
                   {
                           "name": "centos6"
                   }
           },
           "context":
           {
                   "aps":
                   {
                           "link": "strong",
                           "href": "/aps/2/resources/9284f8d3-8ad7-4327-948c-22f780a18fa6",
                           "id": "9284f8d3-8ad7-4327-948c-22f780a18fa6"
                   }
           },
           "offer":
           {
                   "aps":
                   {
                           "link": "strong",
                           "href": "/aps/2/resources/01a1ecd0-0911-450a-b0a7-a37daf8129fc",
                           "id": "01a1ecd0-0911-450a-b0a7-a37daf8129fc"
                   }
           }
   }
   

   Response:

   HTTP/1.1 200 OK
   

3. Creating the VPS:

   POST /vpscloud/vpses
   
   {
           "aps":
           {
                   "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0",
                   "id": "248c9623-55ef-4856-943c-ecd8c4eb05bf",
                   "status": "aps:provisioning",
                   "revision": 3,
                   "modified": "1927-03-02T06:43:36Z",
                   "package":
                   {
                           "id": "d3ad0a6b-69f1-476f-8aba-cfa72c385978",
                           "href": "/aps/2/packages/d3ad0a6b-69f1-476f-8aba-cfa72c385978"
                   }
           },
           "hardware":
           {
                   "CPU":
                   {
                           "number": 4
                   },
                   "diskspace": 32,
                   "memory": 512
           },
           "name": "vps-222",
           "platform":
           {
                   "OS":
                   {
                           "name": "centos6"
                   }
           },
           "context":
           {
                   "aps":
                   {
                           "link": "strong",
                           "href": "/aps/2/resources/9284f8d3-8ad7-4327-948c-22f780a18fa6",
                           "id": "9284f8d3-8ad7-4327-948c-22f780a18fa6"
                   }
           },
           "offer":
           {
                   "aps":
                   {
                           "link": "strong",
                           "href": "/aps/2/resources/01a1ecd0-0911-450a-b0a7-a37daf8129fc",
                           "id": "01a1ecd0-0911-450a-b0a7-a37daf8129fc"
                   }
           },
           "user":
           {
                   "aps":
                   {
                           "link": "strong",
                           "href": "/aps/2/resources/5888680c-19a9-4e92-b95e-d241c64a8c66",
                           "id": "5888680c-19a9-4e92-b95e-d241c64a8c66"
                   }
           }
   }
   

   Response:

   HTTP/1.1 200 OK
   

← Suspending Resources

Custom Operations →