Enabling Monetization of APIs

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.

Implement workflow extensions

To implement the default subscription workflow, start a new maven project and create a new class named SubscriptionBillingWorkflow. You need to implement the methods as per the source code here. If you need to modify the existing workflow (or even write a new workflow, you can create a new project and a new class. This class name must be the name you use in step 4. You could do so within the implemented methods in the above code. Once you have implemented the workflow, proceed to deploying the workflow extention, which is explained in the section below.

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).
Log in to the WSO2 API Manager web console (https://localhost:9443/carbon) 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"/>
```

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. You can also build it from here.
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 deploy 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.3.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.

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: Charges a fixed fee per request.

Install additional cApp

You can use this additional cApp to generate additional summary data used to feed the 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 WSO2 API-M Analytics web console and navigate to Main > Carbon Applications.
Click Add and upload the downloaded cApp. This deploys the cApp.

You can verify whether the CApp is deployed properly by navigating to Main > Carbon Applications > List in WSO2 API-M Analytics web console.

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 registry and user manager</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.3.0/app/main</billingEngineUrl>
```
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.
Copy and paste the MySQL jar to the /repository/component/lib directory, since the extension workflow uses the MySQL connector.

Test the system

Create a subscription tier in the Admin Portal. For instructions on creating a tier, see Adding a new subscription-level throttling tier.
Log in to the API Publisher (https://localhost:9443/publisher), and deploy the 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.
Sign up using the billing engine. You are re-directed to the API Store with a successful subscription.
Create a new billing plan according to your subscription tier, as shown below.
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 usage.