Subscription Service & API
- Joerg Huber
Overview
A Service Consumer uses the Subscriptions Service API to subscribe to Events published by one or more Service Providers. The Events of each Provider will be asynchronously delivered in FIFO order to the assigned Queue, and can then be accessed by the Consumer.
A subscription may either be created or deleted. Any Service Consumer which intends to subscribe to Events from Service Provider X must first:
Successfully create at least one Queue Instance (see Queue & Message Service & API)
Successfully create a Subscription Instance which joins the specific Service Provider and the specific Queue (this API)
At that point, Events published by the Service Provider will begin asynchronously arriving in the Queue Instance, and can be retrieved by the Consumer in FIFO order. They will stop arriving when and if the Service Consumer deletes the subscription object.
Supported Operations
The Subscription service supports the operations listed below. Detailed Open API documentation of each endpoint of the Subscription API can be found on the Open API page.
Operation Name | HTTP Verb | URL Segment | DELAYED Supported | Events Supported |
|---|---|---|---|---|
Create Single Subscription | POST | subscriptions/subscription | No | No |
Get Single Subscription | GET | subscriptions/{id} | No | No |
Get List of Subscriptions | GET | subscriptions | No | No |
Delete Single Subscription | DELETE | subscriptions/{id} | No | No |
Subscription Payload
Below is a sample Subscription payload. Note that the sample contains all elements. These are returned for any subscription endpoints (HTTP GET). The elements marked with <!-- CREATE REQUEST --> indicate that they are required for the create subscription request (HTTP POST). Details about each element are documented on the Infrastructure Data Model site or the SIF Open API site for the Subscription API.
<subscription id="d3d64274-27b7-11e6-b67b-9e71128cae77">
<zoneId>SuffolkMiddleSchoollSI</zoneId> <!-- CREATE REQUEST -->
<contextId>DEFAULT</contextId> <!-- CREATE REQUEST -->
<serviceType>OBJECT</serviceType> <!-- CREATE REQUEST -->
<messageType>EVENT</messageType> <!-- CREATE REQUEST -->
<serviceName>Student</serviceName> <!-- CREATE REQUEST -->
<subscriptionName>RamseyPortal</subscriptionName> <!-- CREATE REQUEST -->
<queueId>53756efe-18d0-4fd4-84ce-fe824719426d</queueId> <!-- CREATE REQUEST -->
</subscription>id: This property is provided in the response to a subscription creation by the subscription service provider. It is the unique Id of a subscription and must be used for the HTTP GET and HTTP DELETE operations.
subscriptionName: This is a 'readable' name for the subsciption. It has no functional purpose but can be used for a more readable illustartion of a subscription.
servcieType: Currently only the following service types allow subscriptions: OBJECT, FUNCTIONAL and UTILITY. These are the service types that support events.
queueId: The unique Queue Id of the consumer's queue where events for the given subscription shall be pushed onto.
messageType: This element indicates whether the subscription is for a events (EVENT) or delayed requests (REQUEST). Valid values are EVENT or REQUEST. This is an optional element and if not provided the message type is assumed to be EVENT.
Example - Consumer subscribes to events:
A consumer wants StudentPersonal events for the school ‘ABC’ (zoneId) and the DEFAULT context to be put onto the queue with id = ‘studentpersonalqueueABC’. To configure this (assuming the queue with the id = 'studentpersonalqueueABC' exists) a service consumer would create the following subscription:
HTTP POST .../subscriptions/subscription
<subscription>
<zoneId>ABC</zoneId>
<contextId>DEFAULT</contextId>
<serviceType>OBJECT</serviceType>
<serviceName>StudentPersonals</serviceName>
<subscriptionName>Student Events for School ABC</subscriptionName>
<queueId>studentpersonalqueueABC</queueId>
</subscription>
Example - Provider subscribes to delayed requests:
A service provider wants StudentPersonal requests for school ‘ABC’ (zoneId) and the DEFAULT context to be put onto the queue with id = ‘delayedstudentpersonalrequest’. To configure this (assuming the queue with the id = 'delayedstudentpersonalrequest' exists) a service provider would create the following subscription:
HTTP POST .../subscriptions/subscription
<subscription>
<zoneId>ABC</zoneId>
<contextId>DEFAULT</contextId>
<serviceType>OBJECT</serviceType>
<messageType>REQUEST</messageType>
<serviceName>StudentPersonals</serviceName>
<subscriptionName>Delayed Student Requests for School ABC</subscriptionName>
<queueId>delayedstudentpersonalrequest</queueId>
</subscription>Note that the messageType element is required in this case and it must be set to REQUEST.
Subscription Endpoints
A SubscriptionService supports endpoints for creation, deletion and querying of subscriptions. Each subscription is dedicated to or owned by a single consumer. The mechanism by which event messages are placed into a queue based on the subscriptions is an implementation detail of queue manger infrastructure. This section will define only the consumer-facing endpoints of the subscription related endpoints.
Available Operations
The list below summarises the main aspects of the subscription endpoints. More details about the usage, HTTP Headers and {subscription payload} can be found in the Open API documentation of the endpoints. These are not specifically listed here, except if there is a specific dependency that can not be documented via the Open API definition.
Create Subscription
Request
URL and HTTP Verb: HTTP POST .../subscriptions/subscription + {subscription payload}
HTTP Headers: The only mandatory HTTP header is the “Authorization” header.
Response
A complete {subscription payload}. Of importance is the "id" element that holds the unique "subscription id" that is required by many of the subscription specific endpoints as the resource id.
Delete Subscription
Request
URL and HTTP Verb: HTTP DELETE.../subscriptions/{id}
HTTP Headers: The only mandatory HTTP header is the “Authorization” header.
Query Subscription(s)
Request to get a specific Subscription
URL and HTTP Verb: HTTP GET.../subscriptions/{id}
HTTP Headers: The only mandatory HTTP header is the “Authorization” header.
Response
A complete {subscription payload} of the requested subscription. Note that a HTTP Status of 404 is returned if the subscription with the given {id} doesn’t exists or is not owned by the consumer.
Request to get ALL Subscriptions owned by a consumer
URL and HTTP Verb: HTTP GET.../subscriptions
HTTP Headers: The only mandatory HTTP header is the “Authorization” header.
Response
A collection of complete {subscription payloads}. Note that either a HTTP Status of 204 (No Content) or a HTTP Status 200 (ok) with an empty collection of subscriptions is returned if there are no subscriptions owned by the consumer.
Unsupported Operations and Concepts
The following operations or concepts are not supported for the subscription service:
Create multiple subscriptions in one request (Batch Create)
Delete multiple subscriptions in one request (Batch Delete)
Any update operations
Delayed Request/Response