Enabling Monetization of APIs

Introduction

API Monetization is being able to charge developers for APIs that contain business information needed to build applications. This is done using billing plans. WSO2 API Manager allows you to manage, govern and monetize APIs.

A typical use case is where an API creator implements an API and the API publisher publishes the APIs to a gateway by specifying throttling tiers and related security and governance configurations. Allowed users can list the APIs available in the gateway using the API Store. These subscribers can subscribe to these available APIs and invoke them. In this billing model, API subscribers get billed based on the subscribed tiers. In WSO2 API Manager, the throttling tiers act as a billing plan when invoked. In order to define a new billing plan, users need to define a new throttling tier plan in WSO2 API Manager to reflect those business rules.

Subscription workflow

To activate the subscription using throttling tiers, use the WSO2 API Manager Subscription workflow. In the default workflow, subscriptions are automatically active. However, when integrating with the billing engine, subscriptions are active only if the billing engine accepts the user. This behavior can be achieved by extending the default subscription workflow. When a subscriber tries to subscribe to an API after the subscription workflow is configured, they are redirected to the billing engine for authentication, with the API Manager workflow details. Then, the billing engine accepts the user or signs them up as a new user to the system. After the user enrollment is done by the billing engine, the user is redirected back to WSO2 API Manager and the subscription is activated.

To configure the default subscription workflow, follow the instructions given in Implementing Workflow Extensions.

Enabling and disabling billing related developer subscriptions

A developer can subscribe to an API, invoke it and get invoiced for it, but avoid the bill payment. To prevent this, WSO2 API Manager subscriptions can be enabled and disabled at the publisher’s will. If the user doesn’t pay, the publisher can disable the subscription and re-enable it once the payment is made.

To enable/disable subscriptions through the UI,

Sign in to the API Publisher.
https://<hostname>:9443/publisher (e.g.: https://localhost:9443/publisher).
In the HOME menu, click MANAGE SUBSCRIPTIONS.
To disable the subscription of a particular API, click Block. Now, an API Store user is unable to invoke that API until it is re-enabled.

In the Manage Subscriptions tab, subscriptions of the APIs are only visible to the creator of that API. For example, if User1 created 2 APIs and User2 created 1 API, then User1 can only view the subscriptions for the APIs that were created by User1.

Controlling over exposure

Throttling tiers contain a Quota Reach option, which might result in the gateway getting flooded with requests. You can use the Hard Level Throttling option to define the maximum number of requests per minute. For more information, see Setting Maximum Backend Throughput Limits.

Configuring API Manager Analytics

For the billing engine to be able to retrieve data, you have to configure WSO2 API Manager Analytics. The API invocation related events are published to WSO2 APIM Analytics, which then persists all the events and makes them available in internal tables. To help the billing engine work efficiently, you may also want summarized data sets based on the raw event data.

For details on how to configure WSO2 API Manager Analytics, see Configuring APIM Analytics.

Data retrieving model for monetization

Following are the events that are sent to WSO2 DAS:

org.wso2.apimgt.statistics.request
org.wso2.apimgt.statistics.response
org.wso2.apimgt.statistics.fault
org.wso2.apimgt.statistics.throttle
org.wso2.apimgt.statistics.workflow

For more information about the event details, see Introducing the WSO2 API Manager Statistics Model.

The sections below describe how to monetize your API.

Configuring the billing engine

This is a sample billing engine provided for you to test out this feature.

Create a MySQL database called billing. This is the database that will store information regarding the application users, the billing plans, and the invoices.
Download the sample billing engine provided for WSO2 API Manager.
To deploy the .war file in a Tomcat container, start a Tomcat server and deploy the downloaded .war file in its webapps folder.
Locate the deployed webapp and edit the <apim-billing-engine-home>/WEB-INF/classes/datasource.properties file as shown below, in order to enable the webapp to write data into the database and pull data from the Analytics server.

url=jdbc:mysql://localhost:3306/billing
username=root
password=pass
driverClassName=com.mysql.jdbc.Driver
dialect=org.hibernate.dialect.MySQL5InnoDBDialect
apimStoreUrl=https://localhost:9443/
apimUserName=admin
apimPassword=admin
dasUrl=https://localhost:9444/
dasUserName=admin
dasPassword=admin
jksPath=<extracted_apim-billing-engine-home>/WEB-INF/classes/wso2-jks/wso2carbon.jks

Navigate to the main page of the billing engine at http://localhost:8080/apim-billing-engine-1.2.0/app/main.
Sign up as a user.
Log in using the newly created user. This is when the tables are created in the billing database that you created in step 1.

Install additional cApp

You need to use this additional cApp to generate additional summary data used to feed the sample billing engine. This cApp reads the event streams, which contain raw data on the API invocations, in the analytics server and adds a summary record to a new table, THROTTLED_SUMMARY, in the Analytics Server. This table is then read, to generate the invoices in the sample billing engine.

A Carbon Application (C-App) or a CAR file is a collection of artifacts deployable on a WSO2 product instance. These artifacts are usually JAVA-based or XML configurations designed differently for each product in the WSO2 Carbon platform. You can deploy these artifacts to generate services.

A single WSO2 product can have numerous artifacts such as Axis2 services, dataservices, synapse configurations, endpoints, proxy services, mediators, registry resources, BPEL workflows, etc. Usually, these artifacts are created in a development environment and then moved one by one into staging/production environments. Manually configuring artifacts to build up the entire solution this way is a time-consuming task. Instead, you can bundle configuration files and artifacts in a C-App and port web service based solutions across environments more easily. C-Apps allow you to export your entire solution as a single archive file.

Download the cApp from APIM_Billing_2.1.0.car
Log in to the WSO2 API-M Analytics web console and navigate to Main > Carbon Applications.
Click Add and upload the downloaded cApp. This deploys the cApp.

Configuring WSO2 API Manager

Define the data source for the billing engine. Since the workflow extension is used, define the billing engine user details data source configuration in the <API-M home>/repository/conf/datasources/master-datasources.xml file, as given in the example below.

<datasource>
  <name>BILLING_DB</name>
  <description>The datasource used for monetization </description>
  <jndiConfig>
      <name>jdbc/BILLING_DB</name>
  </jndiConfig>
  <definition type="RDBMS">
      <configuration>
          <url>jdbc:mysql://localhost:3306/billing?autoReconnect=true</url>
          <username>root</username>
          <password>pass</password>
          <driverClassName>com.mysql.jdbc.Driver</driverClassName>
          <maxActive>50</maxActive>
          <maxWait>60000</maxWait>
          <testOnBorrow>true</testOnBorrow>
          <validationQuery>SELECT 1</validationQuery>
          <validationInterval>30000</validationInterval>
          <defaultAutoCommit>false</defaultAutoCommit>
      </configuration>
  </definition>
</datasource>

To configure the billing engine URL, open the <API-M home>/repository/conf/api-manager.xml file and add the following configuration under <APIManager>.
```
<billingEngineUrl>http://localhost:8080/apim-billing-engine-1.2.0/app/main</billingEngineUrl>
```
Copy and paste the MySQL JAR to the /repository/component/lib directory, since the extension workflow uses the MySQL connector.
Implement and deploy the subscription workflow, as per the instructions below.
Start the server.
Configure the API Manager to use the implemented workflow in step 4 of the Subscription Creation workflow. Log in to the WSO2 API Manager web console and browse the resources.
Open the /_system/governance/apimgt/applicationdata/workflow-extensions.xml file. Replace the SubscriptionCreation tag with the value given in the example below.
```
<SubscriptionCreation executor="org.wso2.sample.apimgt.workflow.SubscriptionBillingWorkflow"/>
```
Since WSO2 API Manager is configured for monetization, enable the API status to free or premium. To enable this flag, edit the registry location, log in to the management console and open the _system/config/apimgt/applicationdata/tenant-conf.json file. Make the changes given below:
1. To enable monetization, set the EnableMonetization property to true.
2. To define if the unlimited tier is paid, set the IsUnlimitedTierPaid property to true.

Implement workflow extensions

In order to redirect to a billing engine to set up the billing account information, you need to configure it through a workflow. You can use the Subscription Creation workflow. When this workflow is configured, when a subscriber tries to subscribe, they are redirected to the billing engine. To configure the default subscription workflow, start a new maven project and create a new class named SubscriptionBillingWorkflow. You can view the source code here.

Deploying the extended workflow

Build the maven project (subs-billing-workflow in the source). Optionally, you can download the built jar file from here.
Copy and paste the built jar into the <API-M_HOME>/repository/component/lib folder (If you already started the server, restart it before proceeding further).

Test the system

Log into the admin portal (https://localhost:9443/admin) using admin credentials.
Create a subscription tier in the Admin Portal. For instructions on creating a tier, see Adding a new subscription-level throttling tier. This tier enables a subscription to be throttled based on the configurations given.
Log in to the API Publisher (https://localhost:9443/publisher), and deploy sample API.
Edit the sample API. Go to the Manage tab and select the new tier you created in the previous step. Click Publish.

For details on editing APIs, see Create and Publish an API.
Log in to the API Store.
Subscribe to the sample API using the Default Application or create a new application and subscribe. You are re-directed to the billing engine if you subscribe with a user that is not signed up in the billing engine.
In case the user is not available, sign up using the billing engine.
Log in once more to the billing engine hosted in the Tomcat server (http://localhost:8080/apim-billing-engine-1.2.0/app/main).
Create a new billing plan on the billing engine according to your subscription tier, as shown below. Note that when using the provided billing engine for testing purposes, use the same name as the subscription tier's name you used in step 2. You can select the Define Standard Plan if you wish to create a subscription based usage plan, or the Define Usage Plan if you wish to create a request-based usage plan. For this sample testing, we will create a subscription based usage plan. Select the Define Standard Plan and give the same name of the tier you created in step 2.

You can define two different types of billing plans based on the WSO2 API Manager billing model,
- Subscription-based usage plan: Charges based on the subscription fee and fee per additional request.
- Request-based usage plan: Charge a fixed fee per request.
Invoke the sample API from the API Store.
Go to the billing engine and generate an invoice, as shown below.

Select the correct plan and month, in order to generate the invoice.
Your invoice is generated based on the usage.