Aliro Subscription Protocol

This API is proposed to handle the interaction between a subscription application and other applications. A subscription application is taken to be an application that manages the provision of bundles of services as packages. Typically, the packages can be purchased by users and the subscription application is responsible for handling the payments, dealing with expiry of subscriptions and their possible renewal, and generally managing the process. It is assumed that subscription applications are interchangeable, or even that there could be more than one subscription application installed at one time.

Currently, there are assumed to be two kinds of control within a package. One is handled by giving a role (in a role based access control - RBAC - context) to a user as part of a subscription. For so long as the subscription is active, the user will have that role. When the subscription expires, the user will cease to have that role, but may perhaps be given another role to indicate that they are an expired subscriber. With this kind of control, other applications can be affected at arm's length, through the RBAC system. The subscription application varies the status of users in respect of their roles, and other applications treat users according to their roles. No direct communication between the subscription application and the other applications is needed in this case.

The other kind of control is where a specific quantity of something is involved. For example, a control might be the number of times an advertisement is clicked on, or the number of files that may be downloaded. In this case, an application other than the subscription application is involved and needs to cooperate with the subscription application. This document describes how that cooperation can be achieved in a flexible way.

Discovering possible controls

When the subscription application is being used to set up a package, it needs to know what elements are available. It can find out directly from the RBAC system what roles exist, and it can dynamically create new roles. To find out what resources can be offered with a counter, the subscription application should trigger an event, which will be handled by a plugin in any application that provides countable controls. The event is called whatSubscriptionControls and no parameters are passed. Each application that is able to handle a counted control should implement a plugin that is activated by the whatSubscriptionControls event. The plugin should return an array of controls, and each control is an object having the properties formalname, resourceID and name. The formalname is the identifier that is used to install the application that is responding and is therefore unique in the system. It is a string. The resourceID is meaningful to the application, and where multiple possible resources are controllable, identifies one particular resource. It is an integer, and although the application that returns it may internally have a more complex way to identify resources, it takes responsibility for mapping this into an integer for use by the subscription application. The name is an informative name for the application and resource, suitable for the web site manager to pick it out from a list as something to be included in a subscription. It is a string.

Discovering possible subscription roles

Although the subscription application can find out from the RBAC system all the roles that are in use, it cannot find out roles that might affect other applications but have not yet been used. To support these roles and to assist the subscription application, other applications should also implement a plugin that responds to the whatSubscriptionRoles event. The plugin should return an array of objects, each of which has the properties formalname, role and name. The formalname is the identifier that is used to install the application that is responding and is therefore unique in the system. It is a string. The role is the name of the role as the application will use it in questioning the RBAC system, and is a string. The name is an informative name for how the application makes use of the role, suitable for the web site manager to pick it out from a list as something to be included in a subscription. It is a string.

Querying the balance available

A subscription enabled application does not know the identity of the subscription application, since the API leaves open the possibility of different such applications. The interface to query what is still available is therefore also implemented using a plugin, but this time, the plugin must be implemented by the subscription application. It responds to the querySubscriptionCount event. When an application is about to deliver a resource that may be controlled (and it is a matter for the administrator interface of that application to settle what resources should be controlled) it triggers the querySubscriptionCount event.

Parameters passed are formalname, resourceID and userID. The first two parameters are the same as those used when discovering possible controls. The third parameter is an integer that identifies the user who wishes to consume the resource. When the subscription application enters a subscription, it is for a particular user, and identifies the resources that are included by reference to a package that is aware of the formalname and resourceID for each countable element. The subscription application also has an initial quantity associated with an element of a package, and when a user subscription is created, the balance is set to this initial quantity. The parameters given are therefore sufficient to enable the subscription application to identify the resource and to determine the current balance held by the user, if any. The balance is returned by the plugin as an integer.

Since the design allows for the possibility of multiple subscription applications, the counts returned from triggering querySubscriptionCount should be added together to decide whether the user has sufficient balance to proceed. It is up to the application to deal with the user appropriately.

Decrementing the balance

This is separated from the query because in some cases the resource may not be used, even though a query was made on the balance available. Otherwise, similar principles apply. In this case, the application should trigger the decrementSubscriptionCount event. The parameters are the same three as for the query along with an additional, optional parameter. The full parameter list is therefore formalname, resourceID, userID and decrement. The first three are as described in the previous paragraph. The decrement parameter is the number by which the user's available balance should be reduced. It defaults to one.

The plugin implemented by the subscription application to handle the decrementSubscriptionCount event should receive the decrement parameter by name (that is, coded with an ampersand in front of the variable name). The plugin should decrement its record for the specified resource and user by the amount given in the parameter, or by as much as it can. The parameter should be reduced by the amount that has been taken from the user's balance. It is somewhat unlikely that this feature would be exploited, but in principle it is thus possible for the available resource to be taken from more than one subscription manager.