11436 SSO

API Facade Design Pattern: A simple interface to a complex system

Brian Mulloy
Mar 16, 2012

In the first post about the API facade, we concluded by recommending that the best solution to the problem of exposing complex back-end systems' functionality in a way that's useful for app developers is to implement an API facade pattern. This time we'll look at the basic steps to implement an API facade.

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 looks like from the perspective of the app developer and end-user of the apps they create.

Use the façade pattern when you want to provide a simple interface to a complex subsystem. Subsystems often get more complex as they evolve.” Design Patterns – Elements of Reusable Object-Oriented Software  (Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides)

The developer and the app that consume the API are on top. The API façade isolates the developer and the application and the API. Making a clean design in the facade allows you to decompose one really hard problem into a few simpler problems.

Implementing an API façade pattern involves three basic steps.

1 - Design the ideal API – design the URLs, request parameters and responses, payloads, headers, query parameters, and so on. The API design should be self-consistent.

2 - Implement the design with data stubs. This allows application developers to use your API and give you feedback even before your API is connected to internal systems.

3 - Mediate or integrate between the façade and the systems.

Three Small Problems  

Using the three-step approach you’ve decomposed one big problem to three smaller problems.  If you try to solve the one big problem, you’ll be starting in code, and trying to build up from your business logic (systems of record) to a clean API interface. You would be exposing objects or tables or RSS feeds from each silo, mapping each to XML in the right format before exposing to the app. It is a machine–to-machine orientation focused around an app and is difficult to get this right.

 One Big Problem

Taking the façade pattern approach helps shift the thinking from a silo approach in a number of important ways. First, you can get buy in around each of the three separate steps and have people more clearly understand how you’re taking a pragmatic approach to the design. Secondly, the orientation shifts from the app to the app developer. The goal becomes to ensure that the app developer can use your API because the design is self-consistent and intuitive.

Because of where it is in the architecture, the façade becomes an interesting gateway. You can now have the façade implement the handling of common patterns (for pagination, queries, ordering, sorting, etc.), authentication, authorization, versioning, and so on, uniformly across the API. (This is a big topic, which we'll delve into later.)

Other benefits for the API team include being more easily able to adapt to different use cases regardless of whether they are internal developer, partner, or open scenarios. The API team will be able to keep pace with the changing needs of developers, including the ever-changing protocols and languages. It is also easier to extend an API by building out more capability from your enterprise or plugging in additional existing systems.

Next time, we'll look at common facade patterns.

Creating World-Class Developer Experiences