Implementing an API Façade with the WSO2 API Management Platform

[Based on a post originally appearing at http://asanka.abeysinghe.org.]

In my previous post I described about the reference architecture of API Façade. This post gives implementation details using the WSO2 API Management Platform and the WSO2 ESB.

Business scenario: A backend service with SOAP binding required to expose as a RESTful service and secured using OAuth. Consumers require responses in either XML or JSON using the same API.

Technical requirements: SOAP to REST protocol switching, content negotiation, XML to JSON conversion.

Reference architecture

Based on the recommended API Façade Pattern in my previous blog, the architecture looks like following diagram:

APIFacade-blog-refarc1

The API Gateway (Gateway is one of the roles in API Management Platform) will expose the RESTful API. The Mediation layer will do the protocol bridging and connect to a backend service with the SOAP binding.

Lets look at the implementation with WSO2 middleware products:

APIFacade-blog-refarc2

WSO2 API Manager and WSO2 ESB will be the primary middleware components used to build this Façade pattern.

Mediation logic (using standard EIP notations) looks like below.

APIFacade-blog-mediation

API definition in API Manager (Gateway)

Screen Shot 2013-05-04 at 7.29.12 AM

Mediation in ESB

Screen Shot 2013-05-04 at 7.23.19 AM

Commands to Invoke the API

XML response :
curl -v -H "Authorization: Bearer zBAIbMiXR4AJjvWuyrCgGYgK2Osa" -X GET
http://localhost:8280/ordersoap/1.0.0/view/JBLU
Screen Shot 2013-05-04 at 9.55.31 AM

 

JSON response:
curl -v -H "Authorization: Bearer zBAIbMiXR4AJjvWuyrCgGYgK2Osa" -X GET
http://localhost:8280/ordersoap/1.0.0/view/JBLU -H "Accept: application/json"

Screen Shot 2013-05-04 at 9.57.38 AM

To view the JSON message properly in CMD

curl -v -H "Authorization: Bearer zBAIbMiXR4AJjvWuyrCgGYgK2Osa" -X GET
http://localhost:8280/ordersoap/1.0.0/view/JBLU -H "Accept: application/json" | python -mjson.tool

In the above sample WSO2 API Manager running with default offset (0) and WSO2 ESB running with offset 3.

Note: If you want to use the anti-pattern of doing both Facade and mediation in the same layer, you can copy the ESB configuration to API Gateway configuration and get the same functional result.

Asanka Abeysinghe
Vice President of Solutions Architecture
Blog: http://asanka.abeysinghe.org

A Pragmatic Approach to the API Façade Pattern

[Based on a post originally appearing at http://asanka.abeysinghe.org/2013/04/pragmatic-approach-to-api-facade-pattern.html.]

Business APIs expose business functionality for access by external and internal consumers.  In technical terms APIs provide an abstract layer for the internal business services to cater to consumer demand.

Most service platforms are not ready-made to safely and cleanly expose internal services to consumers, posing a common challenge for API providers.  Providing a pragmatic approach to the well-known API Façade pattern is the motivation of writing this post.

Fanike-harajuku-store-opening-1cades hide the complexity of internal implementations and provide simple interfaces.  This is a common pattern in computer science but we can even find it in real world too. Lets look at a real world example first: if you walk to a shoe store you find samples displayed in a manner making them easy to pick and select, but if you walk to the back oUntitled 2f the store you will find a massive warehouse with millions of shoes that will not provide an easy way find the correct shoe for you. What does the showroom do?  It provides a facade that displays the shoes in a way that helps buyers select and buy the shoes they want, thereby reducing the complexity and enhancing the buying experience.

Similarly, facades used in computer systems hide complexity and provide a better experience for the consumers (demand).

FacadeDesignPattern

Lets look at how Façade pattern applies for API Management. There is a clear gap between the consumer demand for APIs and the internal services available in each enterprise. As an example, consumers look for Web APIs that can access using REST principles, deliver content using JSON and secured by OAuth addition to that the APIs can be externally accessible and discover. This may map to an authenticated XML/SOAP based service within the enterprise.

API Façade patterns mainly contains four functional layers:

1. Backend services
2. Mediation
3. Façade
4. External format / Demand Slide08

Most commercial API Management solutions treat the Mediation, Façade and Demand as a single functional, architecture as well as deployment layer.

Slide09

If we look at the gap between backend services and the Demand, can a lightweight mediation layer with limited service bindings such as HTTP/s, JMS can build a business API? Are you willing to add the resulting additional wrapper service layer and maintain it?

WSO2 recommends more pragmatic approach by recommending dividing the Façade layer and Mediation layer into clear functional, architecture and deployment layers.

Slide13

This architecture can facilitate heavy mediation including service chaining/orchestration to provide a business friendly API for the consumers. This also allows one to do a clean deployment by inheriting the infrastructure policies appropriate for each layer, as well as scale each architecture layer separately.

Slide15

Implementation of WSO2 API Façade is facilitated by using the WSO2 API Manager to build the Demand and Façade layers, the WSO2 ESB to build the Mediation layer (also add in products like the WSO2 Business Process Server if required) and connect to the existing services. If you are planning to write new set of backend services using standards such as JAX-WS, JAX-RS you can use the WSO2 Application Server as a runtime. In addition to that if there are any other business/technical requirements to build new business APIs you can add them with or after the mediation layer by leveraging the 17+ products in the WSO2 Middleware Platform.

This pragmatic and architecturally rich approach of WSO2 API Façade pattern results many benefits for the API management solutions:

  • Clean architecture by separating the concerns
  • Have a clear separation of internal and external processing of an API call
  • Ability to scale based on the actual usage of each layer
  • Avoid implementing new services or building wrapper service layers
  • Leverage SOA principles with the new Web API architecture
  • Utilize the middleware and go to market quickly

Having said that if you are planning to have a single layer to facilitate all three layers of API Façade, there are no technical limitations in WSO2 API Management Platform to doing that. You can build the mediation by configuring the pre-configured ESB running as the internal dispatching engine of API Gateway.  However for a real-world deployment we recommend that you consider using the flexible, componentized nature of the WSO2 platform to build a clean, scalable, manageable WSO2 API Façade. In my next post I’ll talk more about how to implement this pattern using WSO2 technologies.

Asanka Abeysinghe
Vice President of Solutions Architecture
Blog: http://asanka.abeysinghe.org

Lets talk business agility for your next generation enterprise

We are happy to announce that WSO2 is a Prime Time Sponsor at GigaOm Structure 2013, taking place in San Francisco next month.  The 2-day conference explores how real-time business needs are shaping IT architectures. gigaom-logo

I will be there to present a workshop on Achieving business agility with cloud APIs, cloud-aware apps, and cloud DevOps PaaS. You can also meet the team and get a preview of  new developments in our cloud PaaS and DevOps offerings, at the WSO2 booth.

Recently I’ve been talking a lot about business agility. With today’s “Now Generation”, business stakeholders, who drive revenue growth and customer retention, desire to rapidly seize opportunity and market share.  They often view IT timeframes and capabilities as a poor match for today’s fast business-pace. My webinar last week with David Linthicum addressed some of these concerns. We talked about

  • A path towards agile IT through the use of new approaches and emerging technology
  • New concepts around DevOps improvement
  • The use of emerging PaaS technology
  • Agility best practices that will guide you to success

If you missed out, the slides and recording are avaialble here: http://wso2.org/library/webinars/2013/05/accelerate-business-agility-paas

If you are in the area, I would be more than happy to talk about how we can help, at Structure 2013.

– Chris Haddad is VP of Technology Evangelism at WSO2. He blogs at http://blog.cobia.net/cobiacomm/

Open Conversations on the New Business of Enterprise Software