Previous topic

APS Events

Next topic

Event Notification and Processing

Event Subscriptions

Subscription Structure

An application service may subscribe its resources to events that can happen with the linked resources or the ones in the current security context. Event subscriptions for each subscribed resource are available through the link collection /aps/2/resources/{ID}/aps/subscriptions, where {ID} is the APS ID of the subscribed resource.

Requests for creating event subscriptions must comply with the following schema:

{
  "id": "http://aps-standard.org/types/core/event/subscription/1.0",
  "name": "EventSubscription",
  
  "properties": {
      "id": {
         "type": "string",
         "description": "Event subscription identifier"
      },
      "event": {
         "type": "string",
         "format": "uri",
         "description": "Event type identifier"
      },
      "source": {
         "type": "object",
         "properties": {
             "type": {
                 "type": "string",
                 "format": "uri",
                 "description": "APS Type of source resources"
             },
             "id": {
                 "type": "string",
                 "description": "Concrete resource to listen events from"
             }
         }
      },
      "relation": {
         "type": "string",
         "description": "Relation id for events link/unlink events"
      },
      
      "handler": {
         "type": "string",
         "description": "Operation name to handle Event, should accept only parameter of type EventNotification" 
      }
   }
}

The schema contains the following properties:

  • id uniquely identifies a subscription. It is not included in the request as the APS controller assigns it when creating a subscription.

  • event defines one of the event types listed in the List of Types table. For example:

    • The subscription of type "http://aps-standard.org/core/events/changed" requires the APS controller to send notifications when any properties or aps.status of an event source is changed. Regardless of how many properties are changed by one operation Configure a resource or Update a resource, it will generate only one Changed event.

    • The subscription of type "http://aps-standard.org/core/events/linked" requires the APS controller to notify the subscribers about adding a link to the event source. In this case, the link operation is tracked. If the relation property is presented, then only the links specified by this relation will be tracked.

  • source defines event sources: either all resources of the specified type (URI format), or a certain resource specified by the id property.

    Note

    1. For the Available event type, only an APS type can be requested as the event source.

    2. When subscribing to an APS type, keep in mind the type inheritance. For example, if both type-2 and type-3 implement type-1, then by subscribing to type-1, you will effectively subscribe to all resources instantiated from type-1, type-2, and type-3.

  • relation is relevant when subscribing to the Linked and Unlinked events. It specifies the relation of the source that must be tracked.

  • handler declares the operation that must handle the event notifications on the subscriber side.

Note

The APS controller may consolidate several events of the same type with the same parameters (except serial and time) together and send only the last of them.

Example of a subscription entry tracking the creation of a domain:

{
   "id": "40009029-27C0-492D-B082-8E383FC28C81",
   "event": "http://aps-standard.org/core/events/available",
   "source": {
      "type": "http://parallels.com/aps/types/pa/dns/zone/1.0"
   },
   "handler": "onDomainAvailable"
}

Example of a subscription entry tracking the establishment of links between VPSes and offers:

{
   "id": "E92A9B11-E37F-433B-AAC2-8A73E97A2D96",
   "event": "http://aps-standard.org/core/events/linked",
   "source": {
      "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0"
   },
   "handler": "onVPSofferLink"
}

Subscribing to Events

Any service that is allowed direct access to an APS resource used as anevent source is able to subscribe another APS resource (event target) to events from that source. However, event notifications are delivered to the target APS resource only when some additional requirements are met as specified in the Notification Delivery section.

An application service can subscribe its APS resource to an event type using either declarative or imperative way.

Subscription Parameters

When subscribing an APS resource to an event type, an application service must specify at least the following parameters (for some event types, more parameters might be required):

  • The event type ID in the URI format, for example, http://aps-standard.org/core/events/changed.

  • The source ID: either APS type ID in the URI format if the sources are all APS resources of the specified APS type, or UUID of an APS resource if that resource will be the only event source, for example:

    • "type":"http://parallels.com/aps/types/pa/dns/zone/1.0" for tracking all available domain zones

    • "id":"5ee0fe9d-c812-4af8-a969-5ca28077b032" for tracking the specified APS resource only

  • The event handler that must be a custom operation of the event receiver, for example, onDomainChange.

The Declarative Way

If an APS application needs to subscribe all APS resources instantiated from a certain APS type, the easiest way is to declare this in that APS type. For this purpose, when declaring a custom operation to be used as an event handler, add the “eventSubscription” section as in the following example:

"onVPSavailable": {
   "verb": "POST",
   "path": "/onVPSavailable",
   "eventSubscription": {
       "event" : "http://aps-standard.org/core/events/available",
       "source": {
           "type" : "http://aps-standard.org/samples/event-mgmt/vps/1.0"
       }
   },
   "parameters": {
       "notification": {
           "type": "http://aps-standard.org/types/core/resource/1.0#Notification",
           "required": true,
           "kind": "body"
       }
   }
}

The Imperative Way

In some cases, the declarative way does not help, for example, when an event receiver must be a certain APS resource or some of APS resources, or the event source must be a certain APS resource whose APS ID cannot be found in advance.

An application service can request the APS controller directly to create an event subscription. This must be a POST request containing the subscription structure in its body. The subscription ID should not be specified here, because the APS controller will assign it.

For example, a request for subscribing the 7389d901-701a-4ada-bac1-50b5443b3fa5 resource to the linked events in the resources based on the virtual-environment type looks as follows:

POST /aps/2/resources/7389d901-701a-4ada-bac1-50b5443b3fa5/aps/subscriptions
...

{
   "event": "http://aps-standard.org/core/events/linked",
   "source": {
     "type": "http://www.aps-standard.org/infrastructure/virtual-environment/1"
   },
   "relation": "containers",
   "handler": "onContainerLink"
}

The event subscription ID will be the corresponding response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
...
{
   "id": "8a9cdef0-0348-4d51-9c64-adbbaf8c4540",
   "event": "http://aps-standard.org/core/events/linked",
   "source": {
     "type": "http://www.aps-standard.org/infrastructure/virtual-environment/1"
   },
   "relation": "containers",
   "handler": "onContainerLink"
}

Getting Event Subscriptions

By issuing a GET request, you fetch a list of event subscriptions for a particular event subscriber.

The Pagination header indicates the number of returned items.

Request:

GET /aps/2/resources/7389d901-701a-4ada-bac1-50b5443b3fa5/aps/subscriptions

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Range: items 0-99/100
...
{
   "id": "0DB1F249-9287-4087-9334-05539568BD01",
   "event": "http://aps-standard.org/core/events/linked",
   "source": {
      "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0"
   },
   "handler": "onVPSofferLink"
}

{
   "id": "5EE0FE9D-C812-4AF8-A969-5CA28077B032",
   "event": "http://aps-standard.org/core/events/changed",
   "source": {
       "type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0"
   },
   "handler": "onVPSchange"
}

Deleting Event Subscriptions

By using the following request to identify an event subscription of your application:

GET /aps/2/resources/6afef858-b72a-4c24-879a-edb89cdb107d/aps/subscriptions/

You will get the following response:

[
   {
       "id": "EFC7BB64-0746-4A37-8E08-88242888E6A6",
       "event": "http://aps-standard.org/core/events/removed",
       "source": {
           "type": "http://parallels.com/aps/types/pa/dns/zone/1.0",
       },
       "handler": "onDomainRemove"
   }
]

In that response, you find the APS ID to be used in the DELETE request as follows:

DELETE /aps/2/resources/6afef858-b72a-4c24-879a-edb89cdb107d/aps/subscriptions/EFC7BB64-0746-4A37-8E08-88242888E6A6

Response:

HTTP/1.1 204 OK

Note

If one of the two resources in the subscriber-publisher relation is deleted, either the subscribed resource or the tracked resource, the event subscription will be deleted automatically.