11436 SSO

API Facade Design Pattern: What is it & do I need it?

Brian Mulloy
Mar 16, 2012

The first episode of our Webinar Shorts series on the API Facade Design Pattern is an overview of the idea and theory of API facades. The video and slides are here.

In this post, we'll look at the design problem that arises for API designers when back-end systems of record are too complex to expose directly to application developers. Many businesses find that they need to craft solutions to deal with exposing complex systems.

The advantages of back-end systems of record is that they are stable (have been hardened over time) and dependable (they are running key aspects of your business), but they are often based on legacy technologies and not always easy to expose to Web standards like HTTP. These systems can also have complex interdependencies and they change slowly meaning that they can’t move as quickly as the needs of mobile app developers and keep up with changing formats.

In fact, the problem is not creating an API for just one big system but creating an API for an array of complementary systems that all need to be used to make an API valuable to a developer.

The goal of an API Facade Pattern is to articulate internal systems and make them useful for the app developer. Let's start by looking at a few anti-patterns that we’ve seen and why we believe they don’t work well.

The Build Up Approach

In the build-up approach, a developer exposes the core objects of a big system and puts an XML parsing layer on top.

This approach has merit in that it can get you to market with version 1 quickly. Also, your API team members (your internal developers) already understand the details of the system.

Unfortunately, those details of an internal system at the object level are fine grained and can be confusing to external developers. You’re also exposing details of internal architecture, which is rarely a good idea. This approach can be inflexible because you have 1:1 mapping to how a system works and how it is exposed to API.  In short, building up from the systems of record to the API can be overly complicated.

The Standards Committee Approach

Often the internal systems are owned and managed by different people and departments with different views about how things should work. Designing an API by a standards committee often involves creating a standards document, which defines the schema and URLs and such. All the stakeholders build toward that common goal.

The benefits of this approach include getting to version 1 quickly. You can also create a sense of unification across an organization and a comprehensive strategy, which can be significant accomplishments when you have a large organization and a number of stakeholders and contributors.

A drawback of the standards committee pattern is that it can be slow. Even if you get the document created quickly, getting everybody to implement against it can be slow and can lack adherence. This approach can also lead to a mediocre design as a result of too many compromises.

The Copy Cat Approach

We sometimes see this pattern when an organization is late to market – for example, when their close competitor has already delivered a solution. Again, this approach can get you to version 1 quickly and you may have a built-in adoption curve if the app developers who will use your API are already familiar with your competitor’s API. However, you can end up with an undifferentiated product that is considered an inferior offering in the market of APIs. You might have missed exposing your own key value and differentiation by just copying someone else’s API design.

Solution – The API façade pattern

The best solution starts with thinking about the fundamentals of product management. Your product (your API) needs to be credible, relevant, and differentiated. Once your product manager has decided what the big picture is like, it’s up to the architects.

We recommend you implement an API façade pattern. This pattern gives you a buffer or virtual layer between the interface on top and the API implementation on the bottom. You essentially create a façade – a comprehensive view of what the API should be and importantly it is the view from the perspective of the app developer and end user of the apps they create.

Next time, we'll look at the basic steps to implement an API facade pattern and then at some common facade patterns.

Scaling Microservices