Governing API Subscriptions Through WSO2 API Manager

  • By Nadeesha Gamage
  • 4 Apr, 2014

Objectives

To demonstrate the ability to control API subscriptions via an API subscription workflow.

Prerequisite

WSO2 API Manager, WSO2 Business Process Server

Applies to

WSO2 API Manager

1.6.0 or above

WSO2 Business Process Server

3.1.0 or above

Table of contents

  1. Introduction
  2. Workflows for API subscription approval
  3. Creating the API subscription workflow in WSO2 Business Process Server
  4. Enabling API subscription approval workflow in WSO2 API Manager
  5. Subscribing and approving an API
  6. Integrating workflows for other tasks
  7. Summary

Introduction

Many organizations around the world are adopting an ‘API strategy’ to expose its internal business capabilities as APIs to a wider developer community, both within and outside the organization. Exposing internal APIs to a wider community of developers would require a mechanism to advertise and make APIs available to these developers to encourage a higher level of participation. However, making the API available to a larger community of users has its own inherent issues. These issues would demand a high level of API governance to be enforced to make sure that the API is consumed only by developers who can actually add value to the organization. The ideal ‘API Strategy’ should provide the capability of enforcing effective governance on exposed APIs while making them available to application developers who would be interested in making use of these APIs. WSO2 API Manager provides a platform where APIs can be exposed to a developer community so they can easily find and subscribe to an API. Similarly, WSO2 API Manager also provides many capabilities to govern exposed APIs in an effective manner. This article looks into the ability of integrating a subscription approval workflow to govern API
subscriptions of the exposed APIs via WSO2 API Manager.

Workflows for API subscription approval

WSO2 API Manager provides the ability to enforce a subscription approval workflow for all APIs that are exposed by WSO2 API Manager. This would enable the API Manager to govern subscriptions for APIs. In order to incorporate a subscription approval workflow, WSO2 API Manager needs to be integrated with WSO2 Business Process Server. The Business Process Server would contain BPEL workflows that define the subscription approval
process. The API Manager would provide the required user interface to the subscription approval process where an admin user can approve or reject a subscription request. The subscription approval process can be illustrated by the following image.

Subscription approval process

As illustrated above, the application developer would search for the required APIs and subscribe to them via the API Manager’s API store. Subscribing to an API would trigger an event that would create a task in WSO2 Business Process Server. WSO2 API Manager provides a separate user interface, 'workflow-admin' to facilitate the approval process for workflows integrated with the API Manager. The task that was created by the subscription process would be available for approval from the 'workflow-admin' user interface. The authorized approver can now log into the 'workflow-admin' console and approve/deny the task; this would either approve or deny the request for subscription to the API. If the subscription is approved, the developer can now consume the exposed API; prior to subscription approval, the subscriber or any client application that uses the subscriber’s access tokens will not be able to access the API.

WSO2 API Manager currently ships a sample business process, which also includes an aspect of human interaction that would orchestrate the subscription approval process flow. The business process is defined using WS-BPEL specifications. Similarly, WS-HumanTask specification is used to support the human interaction for the exposed business process. It is also possible to define your own BPEL business process that can orchestrate a subscription approval process suitable for your own organization.

Creating the API subscription workflow in WSO2 Business Process Server

WSO2 API Manager 1.6 and above is shipped with a subscription approval workflow that can be imported to the WSO2 Business Process Server to facilitate the subscription approval process. Business process workflows can be found in the following location of the API Manager distribution < APIM_HOME>/business-processes. The instructions below are provided with the assumption that WSO2 API Manager would run on port offset 0 and WSO2 Business Process Server would run on port offset 2.

  1. Let’s set the port offset of the WSO2 Business Process Server to 2. Port offset can be set from the following location <BPS_HOME>/repository/conf/carbon.xml. Set the port offset value as below
  2. <Offset>2</Offset>
  3. Copy the EPR folder in the < APIM_HOME>/business-processes to the <BPS_HOME>/repository/conf folder. The EPR folder contains the Endpoint references required for the business process.
  4. Start the WSO2 Business Process Server and log into the web console of WSO2 Business Process Server.
  5. Add the BPEL process and the Human Task to WSO2 Business Process Server. This can be done via the admin console of WSO2 Business Process Server
  6. Select the add process button from the navigation panel as shown below and upload the BPEL process available in the following location <
    APIM_HOME>/business-processes/subscription-creation/BPEL/.

    Adding a BPEL Process

  7. Add the Human Task to WSO2 Business Process Server. This can be done by selecting the add Human Task button as shown below. Once inside the add
  8. Human Task page browse and upload the Human Task for subscription approval workflow. The Human Task can be found in <
    APIM_HOME>/business-processes/subscription-creation/HumanTask/

    Adding a Human Task

Enabling API subscription approval workflow in WSO2 API Manager

  1. The default behavior of the subscription approval process would approve the subscription automatically without invoking an external business process. The default approval process should be disabled and a new approval process should be added; this would expose the business processes deployed in WSO2 Business Process Server. The new subscription approval workflow can be enabled in the <APIM_HOME>/repository/conf/api-manager.xml. Enable the SubscriptionCreationWSWorkflowExecutor and disable the existing SubscriptionCreationSimpleWorkflowExecutor workflow as shown below.
  2. 
    https://localhost:9444/services/SubscriptionCreationWorkflowadminadminhttps://localhost:8243/services/WorkflowCallbackService
  3. Once the new API subscription workflow is enabled, start WSO2 API Manager.
  4. Add an API to the API Manager and publish the API to the API Gateway.

Subscribing and approving an API

  1. The newly added API would be available in the API store for subscription. When a developer subscribes to this API, it would be added to the subscribed application list in the subscriber’s API Store. Even though the API is subscribed by the user, the API Manager will not allow it to be consumed until admin
    approves the subscription. The API icon in the subscribed API section would be in gray-scaled indicating that the API is yet to be approved by the admin function. The below image shows a subscribed API that is yet to be approved by admin.
  2. API Store

  3. In order to approve an API, admin has to log into the Workflow-admin in the API Manager. The 'workflow-admin' can be accessed through the following URL.
  4. https://{URL}:{Port}/workflow-admin

    An admin can access the workflow-admin section with his credentials without the need to create a new user.

  5. Once inside the Workflow-admin page, select the subscription creation section from the left hand menu. You would find the pending subscriptions that need to be approved by the admin. Admin can approve the subscription by clicking on the start button and approving the subscription as indicated in the image below. Similarly, the subscription can also be rejected by following the same process.
  6. Workflow-admin for workflow approval

    When the subscription is approved by the admin, the gray-scaled image that appears in the ‘Subscribed API’ section of the user’s API Store would change to its normal color, indicating that the subscription has been approved by the admin. The API Manager would now allow the API to be consumed by the developer’s application.

    It is important to note that the API Manager may still continue to block access to an API for a subscription that has been recently approved. This is due to access token caching at the API Gateway. The API Manager distribution is shipped with access token caching enabled at the API Gateway. This would cache the access token at the API Gateway in the initial request, and this cached key would be used to verify authentication in all subsequent requests until the cache expires. Hence, in a case where an API is accessed prior to approval been granted, the API Manager would reject the invocation and store this information in the cache at API Gateway. This status would remain in the cache of the Gateway until the cache expires. If the API subscription is approved by the admin, this approval would only take effect once the cached key information of the initial request expires in the API Gateway. To avoid such a scenario, caching can be disabled in the API Gateway. Caching can be disabled from the <APIM_HOME>/repository/conf/api-manager.xml.

Integrating workflows for other tasks

WSO2 API Manager provides capabilities to integrate BPEL workflows for other tasks such as application creation and user creation. Sample BPEL and Human Task for these workflows are also available in the ‘business-processes’ folder in the API Manager distribution.

Summary

WSO2 API Manager has the ability to govern the API subscription process by introducing an approval workflow whereby each API subscription would have to be approved by the admin before it can be consumed by the API subscriber. The API Manager has the ability to extend its current approval process to be integrated with a BPEL business process that can be hosted in WSO2 Business Process Server. Integrating an approval process for APIs would provide the ability to an organization to make sure that only legitimate users are able to subscribe to its APIs, irrespective of the larger audience that the API has been advertised to. This would give an organization greater flexibility to advertise the API to a wider community of developers, and at the same time, to govern who can actually subscribe and consume the API via WSO2 API Manager.

About Author

  • Nadeesha Gamage
  • Lead Solutions Engineer
  • WSO2