WSO2 API Manager: Sharing API information with WSO2 ESB in an API Façade Pattern using JSON Web Tokens

Objectives

Ability to share API-related information with the Mediation Layer using JSON web tokens in a de-coupled architecture.

Pre-requisite

WSO2 Enterprise Service Bus, WSO2 API Manager

Introduction

More and more organizations identify the need to expose their business capabilities as APIs to a developer community. This provides the ability for the developers to develop applications that can reap the benefits of the organization’s IT services capabilities and to add value to the organization as well as its customers. Exposing APIs to a developer community would require the organization to focus on aspects of API Management (API lifecycle management, developer management and access control) as well as to ensure that APIs are exposed in formats that are acceptable by the developer community. This would require the organization to follow a layered architecture whereby the API management functionality is performed by a Façade layer and the message transformation required for APIs to be developer friendly, to be done by a Mediation Layer. Similarly, it is important for an organization to separate these two layers; however, the separation of these layers would de-couple the Mediation Layer from API management data that might be required for specific mediation logic. The JSON web tokens (JWT) can be used to provide the flexibility for the Mediation Layer to use API Management data in the mediation logic. This would allow seamless integration of the Façade layer and the Mediation layer in a de-coupled architecture.

Applies to

Table of contents

1. Problem

2. What is an API Façade?

3. JSON web token facilitating API Façade pattern

4. The scenario

5. Running the scenario

6. Improvements

7. References

Problem

A Façade layer would be used in a scenario where multiple APIs are required to be exposed to a developer community. However, due to the heterogeneous nature and the complexity of the backend services, they cannot be exposed directly as APIs to application developers. These backend services would require a certain level of mediation before they would be ready to be exposed to the developers. Hence, it highlights the need to have a separate Mediation layer behind the Façade layer. Due to the dependency between the Façade layer and the Mediation layer, organizations are bound to couple these layers into a single layer (Fig 1.0). Coupling these two layers would increase the complexity in the Façade layer, create architectural limitations, limitations in scalability and would require a significant level of mediation logic to be outside the firewall if the APIs are to be exposed to external developers. The solution to this problem is the use of the API Façade pattern.

What is an API Façade?

API Façade is an interface between API consumers (application developers) and the backend systems of the organization. API Façade would hide the complexity of the backend services from the application developers and provide a unified layer that developers can use for their applications. Refer to Fig 1.1

Even though the API Façade pattern would allow an organization to separate the API Management (Façade layer) from the Mediation layer, de-coupling of these two layers would impact the functionalities of the Mediation layer in instances where the mediation layer would require information relating to the Façade layer. Let’s consider the following scenario; a backend SOAP end-point needs to be exposed as a REST API to Application developers. Similarly, the backend service would require the application name to be passed when making a service call. In an API Façade pattern, the Mediation layer that performs the REST to SOAP transformation would not have the visibility to identify which application is making the API Call. The solution is to use the JWT capabilities of the WSO2 API Manager to allow the API Manager to pass application-related information as a JWT to the Mediation layer or directly to the backend service. The use of the JWT capabilities would allow the Façade layer to focus solely on API Management and pass the information that is only available at the Façade layer to the Mediation layer.

The WSO2 API Manager can be used to build the API Façade layer. The WSO2 API Manager allows the developers to find, explore, subscribe and evaluate APIs through the API Store. The API Store provides a similar graphical experience to that of the Android Store or the Apple App Store. The WSO2 API Manager also provides the ability to manage API subscription as well as the ability to manage developer access tokens. Similarly, the WSO2 Enterprise Service Bus (ESB) can be used to build the Mediation Layer. The WSO2 ESB is capable of providing message enrichment, transformation, routing , protocol mapping and many other functionalities. The combination of using the WSO2 API Manager as the API Façade layer and the WSO2 ESB as the Mediation layer allows the ability to provide a secure, robust solution. Similarly, the ability of the WSO2 API Manager to pass API information available at the API Façade layer to the Mediation layer would allow the Mediation layer to use this information to communicate with the backend services. Refer to Fig 1.2 for more information on how each of the products fits into the architecture.

JSON web token facilitating API Façade pattern

A JWT provides a compact URL safe mode of transferring data among two parties. Data transferred are represented as JavaScript Objects Notations (JSON). Hence, it provides a lightweight data transmission medium compared to XML. In the case of the WSO2 API Manager, JWT would allow vital API access-related information such as information on the API subscriber, subscribed application, API version and many other information to be communicated to the Mediation layer. Given below is the API Manager configuration to enable JWT in the WSO2 API Manager.

API Manager configuration to enable JWT can be found on $CARBON_HOME\repository\conf\api-manager.xml. The following configuration has to be uncommented in the configuration file.

 
X-JWT-Assertion
org.wso2.carbon.apimgt.impl.token.DefaultClaimsRetriever
https://wso2.org/claims
SHA256withRSA
true

A brief description of each property is given below.

The scenario

The scenario involves a backend SOAP service that requires the service invocation to include the application name along with the service request. The service is exposed to the application through the WSO2 API Manager as a RESTful web service.

The process involved can be listed down as follows

1. The API Façade layer would expose the web service as a REST API to the application. The application would make REST invocation to the endpoint exposed by the API Manager.

2. The Façade layer would pass the request to the Mediation Layer along with a JWT, which contains the API access details.

3. The Mediation layer would perform a protocol transformation to create an SOAP message payload from the REST request.

4. JWT is passed from the WSO2 API Manager as an encoded value. This encoded value is required to be decoded at the Mediation layer by the WSO2 ESB to extract the application name required.

5. The Mediation layer would add the application name in the SOAP message payload.

6. The request would be sent to the backend system

The scenario can be illustrated as shown in the diagram below.

Running the scenario

1. Start the WSO2 ESB

WSO2 ESB would be used to build the Mediation layer for this scenario. Let’s begin by starting the WSO2 ESB. The ESB should be started with the port offset of 1 (since we plan to run both the API Manager and ESB together). Port offset can be set in the

<ESB_HOME>/repository/conf/carbon.xml

file where <ESB_HOME> is the ESB binary distribution folder. Set the offset value as below.

1

2. Create the mediations required for the backend service.

With the use of the WSO2 ESB, we create the required mediation that would allow an SOAP service to be exposed as a REST API. Once the configuration is completed, the mediation can be accessed as a REST API from the ESB. The ESB would provide the endpoint of the newly created REST API, which would be invoked by the WSO2 API Manager at a later stage in the process flow.

Given below is the synapse configuration of the ESB.

 

$1 
$2






 
 


 




 







 

3. Start the WSO2 API Manager

Start the WSO2 API Manager. Ensure that the JWT is enabled based on the configuration given above.

4. Publish the API in the API Manager

An API needs to be published in the API Manager that would be made available in the API Store. The API’s production endpoint should point to the API endpoint of the REST API within the WSO2 ESB.

5. Subscribe to the API from the API Manager

The developer needs to subscribe the API that was published. The API should be subscribed to an application group that can be created within the API Manager. This application name would be used by the Mediation layer to identify the application from which the service call is made.

6. Make the service call

A service call can be made to the API Manager’s exposed end-point using the in-built REST client of the WSO2 API Manager or using CURL. Service call should be formed in the following format.

{https://10.200.0.238:8280/sampleAPI/1.0}/getRate/100000

The items inside the curl bracket ({}) should be replaced by the actual API Manager endpoint. The value 100000 represents the amount that is sent to the backend service to calculate the applicable interest rate based on the application. Based on the configuration included in publishing the API, the Authorization token may also be required to be passed in the header. Given below is the format for the Authorization token.

Authorization: Bearer {7SUf1vSmb0omksxri6vdyKO0Jgca}

The values inside the curl bracket ({}) should be replaced with the Authorization token of the application.

Improvements

· This scenario doesn’t have any error handling. To introduce the error handling, an error handling sequence must be introduced to the REST API in the WSO2 ESB.

· Endpoints are specified inside synapse.xml but it is a 'best practice' to store the endpoints in the Governance Registry of the WSO2 ESB.

Reference

https://wso2.com/library/webinars/2012/09/wso2-use-case-api-facade-pattern

https://sumedha.blogspot.com/2012/08/using-jwt-to-send-application-user.html

https://docs.wso2.org/wiki/display/AM130/Configure+JSON+Web+Token+(JWT)+Generation

https://wso2.com/products/enterprise-service-bus

https://wso2.com/products/api-manager

Author

Nadeesha Gamage, Senior Engineer - Technical Sales, WSO2 Inc.