API, Managed API vs SOA

With the explosion of cloud computing, the API (Application Programing Interface) is at the center of all business & IT discussions. In this article, I will explain how an API should be designed and demonstrate how it is sometimes confused with SOA (Service Oriented Architecture). I will also introduce the beneficial operational controls provided by a Managed API.

SOA

Service Oriented Architecture is not a technology; nor is it something you can buy off the shelf. We may have read numerous articles on the topic – yet most of us still miss the point: SOA is an architectural approach that is about organizing the company into reusable units of work. It indirectly calls for major changes everywhere in the organization, and that is the very reason why it is challenging to implement: people and processes are not easy to change.

During the transformation process, “reuse” is heavily sold to upper management as the key driver to increase productivity. SOA is, therefore, an incubator for proper process decomposition: “build once, reuse everywhere, minimize changes” – that’s the leitmotiv.

But in reality, the challenges are somewhere else: Business doesn’t understand the real value of SOA and still today, think about it as an IT concern. With many projects stopped half way through a transformation – it can be difficult to claim success.

API

Thanks to the explosion of cloud computing, Business now understands how to monetize API: Social media integrations, partner/supplier enablers, and mobile channels are just a few areas where API plays a significant role. In fact, the API is becoming a vector of innovation that is clearly understood by all layers: technologists, the business, and even users. Welcome to the API economy!

But besides this apparent success, the challenge remains: whether you say you are doing SOA or building APIs, it is still all about a combination of technology, people, and process.

It is, therefore, important to draw a line between the proper usage of API and SOA. Organizing these concepts will help govern the architecture and ensure proper reuse across the company.

Today most organizations already have some kind of service layer. The goal, then, is to expose functionality in a manageable way that can be easily understood and adopted. That’s where API play a significant role – they are tailored facades aimed at quick adoption.

To properly support this statement, let’s consider the evolution of databases. The first database generations were focused on properly defining data structures and relationships. It quickly became apparent that there was also a need to expose subsets of data in a particular form fitted to a particular group of data consumers. The database “view” was created for that particular purpose.

This is the exact nature of APIs. They are cheap facades aimed at presenting the domain in multiple forms, each optimized for a unique group of API consumers. For clarification, let’s emphasize the differences in the table below:

But enough theory...  let us consider a real example:

Your company captures customer orders on its website. For this purpose you likely defined a set of generic services as such:

• addToOrder(order, offerings) -> order
• submitOrder(order) -> status
• calculatePricing(order) -> order
• calculateTax(order, address) -> order

(in the example above, it is assumed pricing and taxes information is held in the order)

A few weeks later, another group engages and plans to create a similar store but this time, on the IVR channel. In order to improve customer experience on this automated voice interaction system, they also don’t like the shopping cart experience — “customer should only be allowed to purchase one item at the time”. Moreover, the address capture should be limited to the strict minimum: a zip code!

Meeting with the IVR engineers, you agree to provide them a tailored API as follows:

• estimateOrder(offering, zipcode) -> order
• submitOrder(order) -> status

Under the hood, the API orchestrates and reuses the well defined SOA services from your web channel above.

In the end, it's a complete success:

1. Meet customer expectation by providing an API tailored to their specific use case.

2. Achieve the exercise without compromising the integrity and reusability of the service layer.

Managed API

As APIs take a significant place in the integration strategy, organizations will inevitably face issues such as change management, capacity planning, and auditing. That's where Managed API come to play: they are APIs with additional operational controls. Let’s review these controls in the diagram below:

On the right side of the diagram, SOA spans across multiple components with reusable assets: customer, order, product… all these business objects are fine grained and being orchestrated by various levels of business processes and rules. This domain focuses on controlling the scope of change.

On the left side is the API. It’s a light facade which presents a view of the underlying SOA layers. Obviously, the driver is speed and ease of adoption.

In the middle lies the Managed API, an API which carries the following operation controls:

• Multi-tenancy – APIs extend beyond the simple authentication/authorization scheme. Organizations need the ability to present distinct groups of functionalities to specific domains. For instance, a payment service may only be available to the APIs supporting the sales portals.
• Versioning — Since the API may be exposed to the cloud, an organization has little control over its usage. As a consequence, any change to the interface opens the possibility of a break from the clients using the service. Versioning helps to ensure proper change management.
• Service Level Agreement – Systems are typically sized for the heaviest day of the year; however, it can be difficult to size for the unknown. For instance, with mobile channels, it can be difficult to predict the load. An organization should, therefore, consider throttling and quality of service as countermeasures. With these capabilities in mind, an organization can successfully plan capacity and SLA.
• Reporting & Auditing – Planning for the unknown requires extensive analytics capabilities. Understanding the “when” and the “why” are key to quick decision making.

Conclusion

In short, while SOA and API share similar design concerns, they serve different business goals. APIs should be seen as a light facade providing a view into a well-decomposed service domain. It is a business enabler, allowing fast tailored integrations. As a consequence, the API must be engineered with simplicity and ease of adoption in mind.

In this sense, API & SOA complement each other: API drives innovation while SOA drives agility.