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
37 pages
273 KB – 37 Pages
PAGE – 1 ============
Table of Contents Introduction .. .. .. .. 3 Patterns and anti – patterns .. .. .. . 4 The Build Up Approach .. .. .. .. 4 The Standards Committee Approach .. .. .. 5 The Copy Cat Approach .. .. .. .. 6 A simple interface to a complex system .. .. 7 Designing the interface .. .. .. .. 8 Three Small Problems .. .. .. .. .. 9 One Big Problem .. .. Error! Bookmark not defined. Common patterns .. .. .. .. 11 Errors .. .. .. .. .. . 11 Responses & data stubs .. .. .. . 14 URLs .. .. .. .. .. . 15 Limited clients .. .. .. .. . 16 Versions .. .. .. .. .. 17 Data Formats .. .. .. .. . 18 Facades for internal and external systems .. .. . 20 Technology .. .. .. .. 21 Technology for set – up .. .. .. .. .. 21 Technology for versioning, firewalls, caching .. .. 24 Technology for orchestration .. .. .. .. 27 Technology for transformation and compression .. .. . 29 An additional layer of complexity? .. .. .. . 30 People and agility .. .. .. .. 31 Summary .. .. .. .. . 35
PAGE – 2 ============
API Facade Pattern – A Simple Interface to a Complex System 2 API Facade Pattern – A Simple Inte rface to a Complex System Introduction .. .. .. .. 3 Patterns and anti – patterns .. .. .. . 4 The Build Up approach .. .. .. .. 4 The standards committee approach .. .. .. . 5 The copy cat approach .. .. .. .. . 6 A simple interface to a complex system .. .. 7 Designing the interface .. .. .. .. 8 From one big problem to three small problems .. .. .. 9 Common patterns .. .. .. .. 11 Errors .. .. .. .. .. . 11 Responses & data stubs .. .. .. . 14 URLs .. .. .. .. .. . 15 Limited clients .. .. .. .. . 16 Vers ions .. .. .. .. .. 17 Data formats .. .. .. .. .. 18 Facades for internal and external systems .. .. . 20 Technology .. .. .. .. 21 Technology for set – up .. .. .. .. .. 21 Technology for versioning, firewalls, caching .. .. 24 Technology for orchestration .. .. .. .. 27 Technology for transformation and compression .. .. . 29 An additional layer of complexity? .. .. .. . 30 People and agility .. .. .. .. 31 Summary .. .. .. .. . 35 This work is licensed under a Creative Commons Attri bution – NonCommercial 3.0 Unported License .
PAGE – 3 ============
API Facade Pattern – A Simple Interface to a Complex System 3 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 developer s. Because app developers build apps using the APIs provided by an API Team (API provider), m any 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 produc tive 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 interdepend encies and 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 complemen tary 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 use ful for the app developer. SE THE FAÇADE PATTER N WHEN YOU WANT TO P ROVIDE A SIMPLE INTE RFACE TO A COMPLEX SUBSYSTEM . S UBSYSTEMS OFTEN GET MORE COMPLEX AS THEY EVOLVE Design Patterns Elements of Reusable Object – Oriented Software (Erich Gamma, Rich ard Helm, Ralph Johnson, John Vlissides)
PAGE – 4 ============
API Facade Pattern – A Simple Interface to a Complex System 4 Patterns and anti – patterns Let’s start by looking at a few anti – well. The fir Build Up approach. The Build Up a pproach 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 versio n 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 so 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.
PAGE – 5 ============
API Facade Pattern – A Simple Interface to a Complex System 5 The s tandards c ommittee a pproach 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.
PAGE – 6 ============
API Facade Pattern – A Simple Interface to a Complex System 6 The c opy c at a pproach We sometimes see this pattern when an organization is late t o 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 you 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
PAGE – 8 ============
API Facade Pattern – A Simple Interface to a Complex System 8 Designing the interface – our recommended solution to the problem of exposing complex internal s ystems’ functionality in a way that’s useful for app developers is to implement an API facade 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 looks like from the perspective of the app developer and end – user of the apps they create. The developer and the app that consume the API are on top. The API façade isolates the developer and the application and the A PI. 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 sys tems. 3 – Mediate or integrate between the façade and the systems.
PAGE – 9 ============
API Facade Pattern – A Simple Interface to a Complex System 9 From one big problem to t hree s mall p roblems Using the three – one big problem to three smaller problems. build up from your business logic (systems of record) to a clean API interface. You would be exposing objects or tables or RSS f eeds 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.
PAGE – 10 ============
API Facade Pattern – A Simple Interface to a Complex System 10 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 king 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 t he 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 ab le 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.
PAGE – 11 ============
API Facade Pattern – A Simple Interface to a Complex System 11 Common p atterns A n API façade provide s 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 predicta ble and reusable ways. : – Errors – Responses & d ata s tubs – URLs – Versions – Data f ormats 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 HT TP 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 (s hown 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.
273 KB – 37 Pages