API Facade Pattern
API Facade Pattern
Common patterns................................................................................................................................ 11
Common patterns................................................................................................................................ 11
This work is licensed under a Creative Commons Attribution-NonCommercial 3.0 Unported License.
Introduction
The API Facade Design Pattern is a solution to a design problem that arises for API designers when back-end and internal systems of record are too complex to expose directly to application developers. Because app developers build apps using the APIs provided by an API Team (API provider), many businesses find that they need to craft solutions to deal with exposing complex systems. It is beneficial to your API strategy if app developers are as productive as possible and adopt your API. This helps build value within your organization and extend that value proposition out beyond the boundaries of your organization and to the broader market. The advantages of internal systems of record are 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 cant 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.
USE THE FAADE 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)
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. Youre 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 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.
Not only will you provide a simple interface to a complex internal system, but youll also future-proof your environment. As Gamma et. al. observed in Design Patterns Elements of Reusable Object-Oriented Software, systems often get more complex as they evolve and grow. USE THE FAADE 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)
Taking the faade 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 youre 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 faade becomes an interesting gateway. You can now have the faade 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.
10
Common patterns
An API faade provides repeatable patterns to help design the common and critical elements of your API. You'll see by examining a handful of common patterns that you can surface simple interfaces to complex systems in a number of contexts, and in predictable and reusable ways. Well look at the following: - Errors - Responses & data stubs - URLs - Versions - Data formats
Errors
"When I say errors, you say test-driven development" Test-driven development involves building test cases and when they fail they help guide developers towards creating the right app. Because the black box is more stringently enforced with a Web API, this model and the errors are more important in the world of APIs and apps than in other areas of software development. Design the HTTP codes and responses you want Start with a facade, not connected to any internal systems yet and then get the error codes right. In Web API Design: Crafting Interfaces that Developers Love, we talked about the 8 error codes we think are most important (shown below too). (The important error codes may vary for your domain.) Get the error messages in place so that you can start to build your test suite, including the HTTP error codes and the payload response.
11
Control over the facade - raise the error Sometimes you want to explicitly cause a raise to happen. Here's a useful trick and pattern we created for a large API provider, which worked well. It involves putting a raise query parameter in your HTTP request. It will raise that HTTP code. When you are building your test suite, this allows you to ensure your app logic handles exceptions properly.
12
Warning - don't let this make it's way to your production servers. Test and implement - plug internal system into the facade You've designed your set of HTTP codes from the outside in. You have a big internal system, which let's say was built on the .NET framework. Microsoft has an extension of the HTTP status codes - 449 Retry With. You will want to map the 449 to something more aligned with what mobile developers are familiar with today. To do so, you can implement a lookup table and transform the 449 code into a 404 error.
13
So, you started with the design intent - the HTTP codes and responses. You've exerted some controls over the facade by explicitly forcing the raise. And finally, you've tested it all by plugging internal system into the facade.
In the same way we designed the forced raise for errors, you can force the mock. Setting mock = true, you have a shunt in the facade that returns the stub. Again, we're looking at predictable behavior to do test driven development. Warning: It's a good idea to only support the mock attribute on the test server and to raise an error if the mock parameter is included in production.
14
URLs
We think of the URL as the strongest affordance for a well-designed API. This is where the facade pattern begins to shine. The goal is something like this - an app developer wants to do something as simple as see a collection of accounts by doing an HTTP GET on /v2/accounts. However, the internal system may be far more complex than /v2/accounts, like this Salesforce URL.
Doing URL mediation through the facade, you can show the developer on the outside the simple /v2/accounts interface while keeping the complexity of the internal system behind the facade.
15
Limited clients
Certain clients have limitations on the HTTP methods that they support. This is a good scenario to consider in the context of the URL pattern. Take for example a client app that doesn't support HTTP DELETE. You can handle this through the facade by making the method an optional parameter. As the request comes into the facade, the facade changes the HTTP method from GET to DELETE. It also strips the method=delete query parameter and translates to original request of the backend system.
16
Versions
Best practices and principles for versioning your API are described in RESTful API Design: Tips for versioning and in the Web API Design: Crafting Interfaces that Developers Love e-book. Here we'll focus on designing for a scenario in which you need to support more than one version. This is common scenario especially in certain phases of your API's life cycle.
The way to handle this with a facade is to design it such that regardless of which request comes into the facade, you have a shunt in place that points the request to the proper internal system, which serves the response.
17
Data formats
Different developers have different expectations for formats. For example, an HTML5 developer might want JSON responses while a Java developer might depend on libraries to handle SOAP requests and responses. Let's look at how a facade handles this for a developer who needs SOAP. Take a developer who does a POST to get a collection of accounts. The facade mediates the POST into the more complicated internal system and returns SOAP. This is a simple scenario not unlike the URL mapping scenario. There's no real data format mediation happening here.
A more complex mediation happens for example when the developer does an HTTP GET and wants JSON in the response. The facade maps SOAP to JSON on the response, probably using XSLT. Note that the developer has no knowledge of the complexity or the mediation and only knows that they are getting the right format data returned for their app.
18
19
Another use of the same pattern is to easily consume APIs from external systems. All of the same issues and considerations come into play with internal and external systems. We've seen a number of cases in which core businesses rely on external services. We've also seen cases where those service providers change their pricing models and with that the business that is tied to the service provider can see its profit margins shrink, it's SLAs deteriorate, or other business relationship change. A facade pattern can help mitigate risk in cases like this.
With a facade pattern in place, apps that consume the external services can expect a canonical model to consume the APIs. Also, if implemented through the facade, the external services can easily be plugged and replaced. All of the same approaches to implementing common patterns come into play for the external scenario - starting with building out the errors facade and the data stubs. Youll quickly create your canonical model of service consumption.
20
Technology
What are the technologies at the heart of implementing an API faade? Youll need to set up domains and servers, gateways, sub-domain routing. Then youll need to design for versioning, firewalls, caching and finally orchestration, transformation, compression, and authorization.
21
Web server, app server, and API gateway Once you have the DNS and the Cloud Platform set up, you are ready to implement the first patterns, errors and data stubs. To ensure that you have a solid foundation for test-driven development, HTTP codes and error responses need to be in place; you need to be able to stub out data to support mock=true and raise={HTTP code}, and so on. To do so, you need either a static Web server, or an app server for more dynamic content, or an API Gateway (the Swiss army knife for this scenario) in the Cloud Platform.
Subdomain routing and production environment The next step is to set up your production environment. You'll add a new CNAME entry in the DNS so that the production subdomain is api. In our example below, we've pointed api to the same Cloud Platform as in our test environment, but of course you can have different test and production targets if you like. In the API facade, you'll specify the IP address of the target system. Note that the error capability is also here in the production environment. Just as it is important in the test environment, you need to ensure verbose error messages and comprehensive codes in the production environment. 22
With these pieces in place, you'll have requests coming in to api-test and api. In addition to the target IP address, the facade has a shunt that knows where the subdomain is and understands where to point - for example to the data stub server for test or to an internal system for production.
23
24
Firewall You want app requests coming through the API facade. You don't want anyone figuring out the IP address to which your facade is pointing and bypassing it. If the API facade is bypassed, you'll be unable to track the requests and unable to apply the API design logic you've built into your facade. To counteract this, you create a firewall to block all the API traffic with the exception of the trusted IP address of the facade. That is, you ALLOW the IP address of the facade in firewall. Your system is then secure with all requests coming through the facade.
25
Geo DNS and Caching In this scenario, we'll build out our facade functionality some more by adding a geodistributed DNS. The DNS sends the app to a geographically close API facade, based on the source of the request. The number one use case for the geo DNS is caching. This is especially important functionality for apps that have a social network element. You can cache information that doesn't cross-regions so that clients enjoy a fast experience because the facade is caching the API responses where the requests originated. So you've added geo DNS and in the API facade have caching capability. You've told the DNS that based on region; you have 2 different IP addresses to target - either 1.2.3.4 or 1.2.3.5 in our example.
26
The facade in this scenario orchestrates across a number of calls. There are configuration- or policy-orientated orchestration technologies available or you can write the orchestration logic in code. Code is often one of the best orchestration tools but the approach you take will depend on the skills and capacity of the team that's implementing the API facade.
27
28
29
To handle a common use case for verbose and large XML documents, you add a compression engine to your API facade. Not clogging the bandwidth is especially important for mobile apps where large payloads become a problem because they impact the cost of users' data plans and use battery powering the radio. Apps that impact the users' bottom line get uninstalled.
30
31
Who are the people in that system - in the API value chain? The key players include the API team and the app developers.
The API Team Building out a solid API team starts with a strong Web team. The core of that team includes architects, software engineers, operations professionals, QA engineers and database administrators. But dont stop there. Youll also need API-specific roles on the team in the form of an API product manager (the subject matter expert for the company and the domain), an API Designer (technical thinker, critical thinker with a strong sense of design and user-interaction), and what we typically refer to as a Gateway operations person (. One person may play multiple roles, but for a successful API program, youll need to cover all these bases. The Web team and the API specific team in place, youll need some additional roles. Depending on the kind of developers who will develop apps that take advantage of your API, you add different people to the API team. The four main persona of app developer we talk about depends on what kind of API strategy you have whether internal, partner, customer, or open. Internal: The app developer using the API works for the company the API provider. Partner: The developer works for or is a strategic partner. The go-to-market strategy is one with a shared value proposition. Customer: The customer developer is especially important if your organization is a SaaS provider or if a large amount of revenue comes from B2B customers as opposed to consumer end users. Open: The developer in this case is any developer who signs up to build apps against your API.
32
It is our experience that if you target an open scenario you will get things right in the other scenarios. So we finish out this third category of API team member with the open use case in mind. This last set of roles will have only subtle nuances depending on which scenario is your first or primary use case.
One of the most important people is an executive sponsor who will not only help with funding for your initiative but who can also set expectations about the business value an open API brings to the marketplace. The next role is for a community manager who will facilitate two core and critical connections. The first is from the API team to the app developers and the second is helping connect developers with other developers to share expertise and collaborate to spur innovation. The community manager builds and forges relationships both online and in real life situations. While the role for a community manager is clear when you have an open API strategy, even when your strategy is internal, it is valuable to have a person on the team with the mindset of community manager. They will facilitate developer-to-developer interactions and collaborations internally. Its also a great way to learn lessons about running a developer community before you do it externally.
33
For the customer API scenario, you will likely want to add a customer support role. While the developer community manager may play this role, you may need a more typical customer support role that can handle traditional customer tracking systems, follow ups and so on as are expected in typical B2B relationships. For the partner scenario, you will likely need a partner support role. Partner support is very similar to customer support in that there are similar expectations between parties in the business relationship. Then finally, you should consider a business developer. Perhaps this person doubles as the executive sponsor. They are responsible for pushing the API program in the direction of increased business opportunity.
34
Summary
Going back to our API value chain, app developers build apps using the APIs provided by the API Team (API provider). Everybody wins if app developers are as productive as possible and adopt your API quickly. Those app developers will help build the value within your organization and to extend that value proposition out beyond the boundaries of your organization into the broader market. The best way weve found to facilitate this success is to implement an API faade pattern. This pattern gives you a virtual layer between the interface on top and the API implementation on the bottom. It is a comprehensive view of what the API should be. Importantly, it is the view from the perspective of the app developer and end user of the apps they create. You break one major problem (exposing a set of complex internal systems in such a way as to be beneficial for developers) into three smaller problems (designing the ideal API; implementing the design with data stubs; integrating between the faade and the systems).
Using an API facade allows your organization to keep pace with developers in the real world. Their world changes quickly and frequently and they need to make apps that remain competitive in an ever growing and evolving market place. It also has benefits internally (behind the faade) in that it enables an API team to create an extensible API that allows new systems to be plugged in, allowing your organization to keep pace with both the marketplace and with changing internal systems.
35
Resources
Web API Design Crafting Interfaces that Developers Love (Brian Mulloy) RESTful API Design Webinar, 2nd edition, Brian Mulloy, 2011 Apigee API Tech and Best Practices Blog API Craft Google Group
About Apigee Apigee is the leading provider of API products and technology for enterprises and developers. Hundreds of enterprises like Comcast, GameSpy, TransUnion Interactive, Guardian Life and Constant Contact and thousands of developers use Apigee's technology. Enterprises use Apigee for visibility, control and scale of their API strategies. Developers use Apigee to learn, explore and develop API-based applications. Learn more at http://www.apigee.com.
Accelerate your API Strategy Scale Control and Secure your Enterprise Developers Consoles for the APIs you Usergrid - A scalable data platform for mobile apps