API Platform Reference Architecture and Case Studies


APIs are becoming the mainstream approach for exposing Organization’s core functionalities and data to external partners and its own digital apps. As discussed in article “API and SOA Synergy“, APIs are seen as the natural extension of Enterprise Business Services delivered through SOA-ESB layer. For example, a Mortgage calculation functionality delivered through SOA as a Business Service can be made available to internal Branch and Call Center applications as reusable asset, and at the same time it can be extended further in API domain as RESTful API for digital channels. SOA and APIs have synergy and they co-exist.

In SOA paradigm, application functionalities and data take the form of Business Services; in extended digital ecosystem they are shaping into APIs. Having said that, not each and every Business Service will be candidate for API, there should be proper assessment to decide what Enterprise functionalities and data are candidate for APIs.

ESB-Integration layer is the building block for API Management Platform. Organizations having right integration-ESB foundation are better placed to deal with fast paced API economy.

The diagram below depicts the generic runtime Reference Architecture for API Platform (Detailed view of diagram discussed in “API and SOA Synergy” article). APIs are made operational and hosted on API Platform, usually known as API Gateway. The diagram provides end-to-end view of architecture connecting API Consumers to Back-end applications through API Gateway and Integration-ESB platform  (note: enterprise application landscape is shown for Telecom domain as an example)

Enterprise Real-time Integration Reference Architecture: API Platform

Enterprise Real-time Integration Reference Architecture: API Platform

Please refer to “Enterprise Real-time Integration Platform” article to understand role of each Integration Platform

Case Studies
Now let’s look at few case studies based on hypothetical scenarios (based on ideas, suggested) from following business domains. The objective is to demonstrate importance of APIs. We will map these scenarios to reference architecture defined above.

  • Insurance
  • Telecom
  • Manufacturing
  • Travel and leisure

Case Study: Insurance Domain

Domain: Insurance

Functional Area: Policy Capabilities

Let’s assume, a global Life Insurance company decides to enter digital model of collaborative offerings and value added services, thus adding new sales channels and increasing revenue opportunities. Company has its own Marketing-Sales team and also has large base of trusted partners, agents and brokers who sell company’s life insurance products.

API Approach:

  • Company decides to embark on digital channels strategy by building a strategic API platform which exposes key capabilities-services and data through APIs.
  • To begin with, company decides to expose capabilities related to Policies. Company exposes these capabilities through Policy APIs which covers functionalities-data like policy details, premium calculation (for new policies), premium payment and so on.
  • API Consumer base targeted for Policy APIs are – partner/broker/agent applications, authorized third party applications and insurance company’s own mobile-web applications.

Let’s assume Insurance company’s following applications/components are involved. While there could be many functional applications involved (for complete Policy APIs), let’s focus on one application – Policy management application and Premium Calculation capability it offers.

  • Policy Management application – Policy Management application is a back-end mainframe based legacy Business application responsible for managing various policies offered by the company. One of the functionalities offered by this application is the Premium Calculation functionality that can be invoked via submitting request to JMS-messaging queue.
  • Service Platform (ESB) – ESB layer exposes Premium Calculation as a standards-based interoperable Business Service for various consumers. The service is available as SOAP service over Http protocol. In the background, service invokes Premium Calculation functionality offered by ‘Policy Management’ mainframe application over JMS-messaging.
  • API Gateway – API Gateway exposes Policy APIs to API Consumers; one of the capabilities delivered to consumers through Policy APIs is Premium Calculation. The capability is available as RESTful service over Http protocol. In the background, it invokes Premium Calculation Business Service exposed by ESB layer.

Scenario 1:

Insurance company’s internal app developer team uses Policy APIs to build mobile apps for their respective area – mobile app for marketing team and mobile app for customers.

  • Company’s mobile app for marketing – mobile app for marketing is a purpose-built mobile channel app for internal marketing-sales teams; it allows them to inquire various policies/plans offered by company while dealing with prospective customers. One of the functionalities offered by this app is to get premium calculation for a particular term insurance policy/plan based on input parameters such as age, sum assured and term. Internally this app uses Policy APIs exposed by API Gateway to get premium details.
  • Company’s mobile app for customers – mobile app for customers allows customers to manage their existing policies as well as inquire about new policy offerings/premium quote etc. One of the functionalities offered by this app is to get premium calculation for a particular term insurance policy/plan based on input parameters such as age, sum assured and term. Internally this app uses Policy APIs exposed by API Gateway to get premium details.

Now let’s map this scenario to the ‘API Platform’ reference architecture. The diagram below shows the overall flow of Premium Calculation capability. As depicted in the diagram, capability is being used by multiple apps of Organization.

API - Ref Arch Scenario - Premium Calc

Premium Calculation capability (API) in use by Company’s apps

Flow – Company’s mobile app for marketing team to Policy Management application

Step 1b: The mobile app invokes Premium Calculation capability using REST-JSON over Http and waits for the response. This request gets initiated from mobile app on real-time when marketing agent chooses to get premium quote for a particular term insurance plan by providing customer’s age, sum assured and term as input.

Step 2: Premium Calculation API flow hosted on API Gateway transforms JSON object to SOAP-XML message and invokes the Premium Calculation Business Service hosted on ESB platform and waits for the response.

Step 3: Premium Calculation Business Service transforms SOAP-XML message to COBOL copybook format as required by Policy Management mainframe application. It then submits the request to application specific PC request queue (Premium Calculation) and waits for the response.

Step 4: Policy Management application consumes the message from queue and executes functionality to calculate premium for a given age, sum assured and term.

Step 5: Policy Management application returns response (Premium amount) via application specific PC response queue.

Step 6: Premium Calculation Business Service consumes the response and performs the transformation from COBOL copybook format (application specific) to SOAP-XML message format and returns the response to Premium Calculation API flow (Service Consumer).

Step 7: Premium Calculation flow receives the response and performs the transformation from SOAP-XML format to JSON format.

Step 8b: Premium Calculation API flow returns the JSON response back to mobile app over http.

The flow for mobile app for customer to Policy Management application is exactly same as above.

Note: Security aspects across all layers are omitted to keep overall flow simple.

Scenario 2:

Now let’s see how other internal and external app developers communities can leverage Policy APIs exposed by Insurance company to build apps. This scenario will also demonstrate how company’s API strategy and publishing Policy APIs (through develop portal) will help company with increased revenue opportunities, sales and cost-savings.

Let’s assume following new external and internal consumers are interested in Insurance company’s Policy APIs:

External: Third Party Policy Comparison service provider

  • Third party Policy Comparison service provider is creating new Policy Comparison application that provides comparison of term insurance policies offered by various insurance companies.
  • Third party app developer community is building Policy Comparison web app by leveraging Policy related interfaces exposed by various insurance companies. This app leverages Policy APIs of above Insurance company to get details about policies/plans offered.
  • At runtime, Policy Comparison web app will invoke Premium Calculation interfaces exposed by respective insurance companies to get premium amount of term insurance policies selected by customer for comparison purpose. The app will invoke Premium Calculation capability of above Insurance company (exposed through Policy APIs) to get premium amount.

 External: Trusted Home Loan Partner (Bank) –

  • One of the Banking partners of above Insurance company is creating a new home loan product. To attract prospective customers, it decides to provide them with more flexibility in terms of risk coverage through optional term insurance plan.
  • Bank decides to use term insurance capabilities offered by above Insurance company. The Bank’s app developer community builds new Home Loan mobile app. This app leverages Policy APIs of Insurance company to add term insurance feature to the app.
  • At runtime, Home Loan mobile app will invoke Premium Calculation capability of Insurance company (exposed through Policy APIs) to get premium quote for a given home loan amount (along with other parameters such as borrower’s age and loan term etc.) and bundle the same in its final home loan package before presenting to the customer.

Internal: Other Business Unit

  • Insurance company’s internal business unit responsible for managing agents and brokers decides to build dedicated mobile app for agents-brokers empowering them to access existing/new policies-plans anytime/anywhere while serving the customers.
  • Internal app developer community builds mobile app for agents-brokers leveraging already available Policy APIs

So Policy APIs of above Insurance company are consumed by:

  • External Third party Policy Comparison web app
  • External Trusted partner Home Loan mobile app
  • Internal mobile app for Agents and Brokers
  • Internal mobile app for Customers
  • Internal mobile app for Marketing

However, this does not mean that above will be the only consumers of Policy APIs; the list will keep growing with more and more internal and external API Consumers.

Now let’s map this scenario to the ‘API Platform’ reference architecture. The diagram below shows the overall flow for Premium Calculation capability with all above API Consumers invoking capability using REST architecture style.

API - Ref Arch Scenario - Premium Calc All Consumers

Premium Calculation capability (API) in use by multiple internal and external apps

What this API strategy means to an Insurance company discussed in above case study:

  • New sales channels and more revenue opportunities. (For Ex. chances of revenue through External Policy comparison web app, Banking partner home loan app)
  • The accessibility of core policy capabilities (converted to Policy APIs) through multiple channels anytime/anywhere means more cost savings from lesser call volume to company’s customer contact center, leading to better and efficient utilization of work force.

Now let’s look at few more case studies from Telecom, Manufacturing and Travel-Leisure domain briefly, without getting into too much details.

Case Study: Telecom Domain

Let’s assume a scenario where a cloud based Third-Party is building a value added telecom mobile app for end users (customers). End users can register their telecom service providers (TSP) with Third-Party app for the various services they are subscribing from these different providers (such as mobile plans, broadband-homephone etc). Third-Party app then provides a unified interface for customers (end users) who can view their Bills with these various providers through a single app in a simplified format (as against going to individual TSP’s web/mobile app for services). In addition to providing simplified view of Billing data, Third-Party app also provides Bill payment facilities and comparison of various plans from these TSPs.

The diagram below shows how Third-Party app leverages Bill Details capability (exposed through Billing APIs) of one of the Telecom Service Providers to retrieve Bill Details.

API - Ref Arch Scenario - Bill details v1

TSP’s Billing Capabilities consumed by Third party value added app

As depicted in the diagram, TSP’s Bills details capability is exposed as RESTful API to external consumers; Bill Details SOA-Business Service is available over JMS protocol from ESB layer to various service consumers (Including Bill details API flow ), so in this scenario Bill Details API flow hosted on API Gateway transforms JSON message to SOAP-XML format and does a protocol mediation from Http to JMS. Bill Details API flow submits SOAP-XML request to Business Service hosted on ESB via JMS and waits for the response on reply queue. Bill Details Business service internally uses Billing system adapter (application adapter) to retrieve Bill Details from Retail Billing system.

Case Study: Manufacturing Domain

Let’s assume a scenario where a global smartphone accessories manufacturing company exposes product capabilities through Product APIs. The diagram below shows company’s own mobile app (for dealers-OEMs) and external e-Retailers web app as consumer of Product Catalog capability (exposed through Product APIs). Again this does not mean that the above will be the only consumers of Product APIs; the list will keep growing as more and more e-Retailers/third parties consume Product APIs of accessories manufacturing company. From accessories manufacturing company’s perspective (API Provider), this means more revenue opportunities by sharing product catalogs and related capabilities (Ex. Placing Order etc.) across e-Retailers/third parties in real-time.

API - Ref Arch Scenario - Product Catalog

Product Catalog capability in use by internal and external app

As depicted in the diagram, there is no ESB layer (Business Service) involved in this case, API flow directly invokes SOAP based interface exposed by back-end ‘Product and Catalog Management’ application.

Case Study: Travel and Leisure Domain

While we have discussed above case studies from the perspective of single API Provider and multiple API Consumers, let’s look at this case study from a different perspective where a particular API Consumer uses APIs exposed by multiple API Providers to offer better deals to customers.

Let’s assume a scenario where the Global Travel and Tourism Company is building a web app for customers offering various tour packages which covers global destinations. The web app internally uses Hotel APIs exposed by various service providers to get competitive deals on hotels; though app fetches details from all these providers, it internally chooses the best deal offered, and at the same time increasing its profit margin. Hotel APIs exposed by various service providers offers capabilities to search, check availability and book hotels.

service providers

Hotel Consolidator – Pre-books hotels in top destinations and maintains inventory. It exposes unified APIs for clients/partners for searching, checking availability and booking hotels across top destinations.

Domestic Travel Company – Company is the preferred domestic partner of Global Travel-Tourism Company (mentioned above) and it exposes search-availability-booking services for hotels as APIs.

Large Hotel Business – Apart from having its own booking portal, large hotel business exposes APIs for tourism partners to check availability and book rooms.

The diagram below shows how Global Travel and Tourism Company integrates with various service providers (Hotel Consolidator, Domestic Travel Company and Hotel itself) through the notion of Hotel APIs exposed by them.

API - Ref Arch Scenario - Hotel APIs

Hotel APIs in use by Global Travel and Tourism Company

As depicted in the diagram, some of these service providers (Hotel Consolidator and Large Hotel Business) could be cloud based service providers who are making their services/APIs available to numerous partners by hosting their applications on cost-effective cloud infrastructure; these providers are able to participate in overall value chain quickly with minimal investment due to cloud computing model. (So essentially, this case study also demonstrate the concept discussed in article “Mobility, Cloud and Real-time Integration” – Organization leveraging Mobility and Cloud trends for participating in growing digital ecosystem of collaborative offerings and value added services with minimal investment.)

Please refer to ‘Publication Schedule’ page for upcoming articles.

9 thoughts on “API Platform Reference Architecture and Case Studies

Leave a Reply