Monetization solution for an API Management system

Introduction

In brief API Monetization with WSO2 API Manager is billing subscribers of a tenant. But WSO2 API Manager doesn't support out of the box for this. Reason is there would be tons of parameters to tackle if the product is supported out of the box for this. ex: billing rules, payment gateways and etc. 

So API Manager provides extension points to develop your own monetization solution. In this article I'll provide some brief description on those extension points and the available feature options you need to know

Monetization feature

This monetization feature is defined on API throttling tiers. Basically Subscribers will get billed according to the throttling tier they have subscribed to a particular API. So if your tenant admin wants to enable monetization for his/her tenant followings are options he should keep in mind to configure.

Defining Throttiling Tiers

API Manager previous versions, tenant had to define the tiers by editing tiers.xml in the registry. From API Manager 1.10 release this can be done from the admin dashboard [1]. The important thing I want to highlight here is following fields.

Stop On Quota Reach

This indicates the action to be taken when a user goes beyond the allocated quota. If checked, the user's requests will be dropped and an error response (HTTP Status code 429) will be given. If unchecked, the requests will be allowed to pass through.

Billing Plan

This is where you define whether this is Paid or a Free plan. In the development perspective of the underlying billing engine developer will use this to differentiate the workflow for the API subscription.

Description

Tenant admin should keep in mind to add a comprehensive description about the tier, because this is the only information will be shown at the API subscription. Otherwise subscriber might not have enough information to select an appropriate plan.          

Enable Monetization

First you have to enable monetization in API Manager. By enabling tenant's APIs in the store would get labeled as Paid, Free and Freemium. These labels are applied to those APIs depending on the tiers they are published on.  API throttling tier billing plans are either Paid or Free. If and API is published in tiers with a composition of those billing plans that API would be labeled as a Freemium, otherwise it would be labeled as either Paid or Free. 

Tenant admin can enable monetization as in the document [2]

Now you are good to go from setting up the flags for a tenant to use monetization. Next you want to engage your billing engine to API Manager to do metering and billing the subscribers of a tenant. 

To do this your system should have additional UIs/ functionality to enable monetization these should be developed externally. When a tenant enables monetization from your UIs, that particular tenant's default workflows should get replaced with your own Workflow executors. Process of developing your own workflows will be described later in this article. 

Replacement happen by calling the registry admin service (org.wso2.carbon.registry.core.service.RegistryService) and tenant registry loader admin service (org.wso2.carbon.registry.core.service.TenantRegistryLoader). You just have to replace it with your custom workflow executor configurations. [3][4] describes workflow extensions you can create and what are configurations you should add.

For an example say you have developed a custom API subscription workflow then you'll have to replace the following configuration

<SubscriptionCreation executor="org.wso2.carbon.apimgt.impl.workflow.SubscriptionCreationWSWorkflowExecutor">
    <Property name="serviceEndpoint">http://localhost:9765/services/SubscriptionApprovalWorkFlowProcess/</Property>
    <Property name="username">admin</Property>
    <Property name="password">admin</Property>
    <Property name="callbackURL">https://localhost:8243/services/WorkflowCallbackService</Property>
</SubscriptionCreation>

with your own API subscription workflow executor.

<SubscriptionCreation executor="org.wso2.carbon.cloud.monetization.apimgt.workflows.SubscriptionCreationWorkflowExecutor">
    <Property name="serviceEndpoint">https://milestones.appfactory.wso2.com:9443/services/APICloudMonetizationService/</Property>
    <Property name="username">rajith.siriw.ardana.gmail.com@mustanggt350</Property>
    <Property name="password">Admin</Property>
</SubscriptionCreation>

in registry location /_system/governance/apimgt/applicationdata/workflow-extensions.xml

Workflow executors 

When you are developing an API Management solution you might want to customize the API subscription flow, API deletion flow and the Application deletion flow to fit your requirements.
For an example say if you want to bill your subscribers and you want those information collected when they are subscribing to an API and etc. Best way to tackle those scenarios would be to use the extension points provided by API Manager which are called workflows. You just have to write your own workflows to replace the default subscription, subscription deletion, application deletion and etc workflows. You can find how to write workflow from the document [4]

Additionally for the document [4], when you are developing your own workflow executors, HTTP redirect to your pages residing in API Manager store and there is no domain change

• You'll have to set the redirection confirmation message to null. Otherwise null message will pop up. this is a bug in API Manager 1.10.
• You might not want to resume the workflow using the REST/SOAP endpoints described in [5] after your flow is executed. In that case you can use jaggery workflow modules resumeworkflow method.

References

[1] https://docs.wso2.com/display/AM1100/Defining+Throttling+Tiers
[2] https://docs.wso2.com/display/AM1100/Configuring+API+Monetization+Category+Labels
[3] https://docs.wso2.com/display/AM1100/Managing+Workflow+Extensions
[4] https://docs.wso2.com/display/AM1100/Configuring+HTTP+Redirection+for+Workflows
[5] https://docs.wso2.com/display/AM1100/Invoking+the+API+Manager+from+the+BPEL+Engine