Essential API Facade Patterns: One Phase to Two Phase Conversion (Episode 3)

Editor's Notes

1. I am Santanu DeyI am a senior solution architect here at Apigee – I am focused on Integration – primarily API based Integration & and a little bit beyond
2. As an API Provider we often come across a situation where the backend core system exposes a 2 phase Interface – for simplicity of consumption we have to convert it to one phase REST APIWHY DO WE WANT TO DO THIS?The essence of API integration over enterprise style integration is extra emphasis on simplicity. So if it makes it easy for a Developer to consume the API – lets better make it simple.Traditionally Enterprise systems expose interfaces compatible with 2 phase commit. 2 phase commit is a very well established pattern. This is very useful for designing transactions in a reliable way. But these are not so appropriate for the edge of the enterprise. Where innovation is driven by ease of consumption of resources. The underlying enterprise integration tools should not dictate how APIs are defined, exposed and integrated. That is the core motivation for this pattern.
3. It is common for backend Interfaces running on enterprise integration software exposes a two phase interface. From the perspective of the distributed transactions – when an Interface supports two phase commit we can say it is a two phase API
4. A quick and high-level recap how a typical tow phase transaction work in the distributed transaction scenario– there are two types of resources. A transaction coordinator or a transaction Manager. And then the participating resources.At the core of two phase distributed transaction - each participating resource supports two phases – to be able to participate in a distributed two phase transaction.How does it all happen?Prepare or vote - A “commit” vote means that participants can carry out the commit if told to – there is no inconsistency or exception expected from that component
5. Commit or Rollback. In this phase, the transaction coordinator instructs each of the participating resourcesto commit or rollback all of the changes that were requested as part of the transaction. A properly executed rollback should return the system to its original state.A commit should result into a consistent state of change across systems.
6. This makes a lot of sense for machine to machine communication in a distributed architectureIn order to reliably carry out distributed transactions – this is a great pattern. A two phase commit that is. But the key question is that is it a good idea for an app to consume a two phase enabled API?
7. I think it is not a good idea for an app to consume a two phase API interface.It is like getting an app to become a transaction coordinator because the API provider supports two phase it is not a great ideaFirst of all When looking into REST one of the first things probably anybody will notice is there isn't any transaction semantics defined. Unlike WS-Transactions for web services.Let us see why it does not sound like a good idea
8. The important one is this –Consider a typical appA browser plugin may be written in java script, an app running on a device or an HTML 5 need have Transactional behavior? Let me emphasize more on the use case in question. Not so much on the technology employed. Are there any real use cases?Let us think about a two phase API example. Thinking about transactions – payment comes in mind. Consider GSMA OneAPI Payment API – the mobile payment API - Yes it has two phases. But in most scenarios – the Developer server is expected to make the calls. So it is a machine to machine architecture. Not a client application to API host.
9. Secondly, making the app a transaction coordinator is kind of forcing the developer to think about roll back, compensation etc.The device run-time is not best suited for heavy logic needed for a two phase commit, roll back or compensationLack of simplicity in the APIs would make it difficult for the developer
10. The Service Composition pattern in Episode 1 listed the other disadvantages of composing multiple service calls from the device – this situation also applies to this case. At least partially here the connections are to the same server….
11. let us assume that the backend has a two phase interface- > Reserve an amount for payment- > Commit the paymentOne of the ways to convert this interface to REST kind of semantics is to just convert the resources to two appropriate corresponding APIs. Like I have shown in the slide. And yes – there would be a way to get the payment resource location as a representation in the reserve response. But this is still away from REST for the problems sighted in the problem segment of our discussion.
12. So the suggested pattern is to not to get influenced by what the backend API signature looks likeThe API Façade should still expose a single resource
13. UML sequence diagram to explain the responsibilities of the API Façade layer in this pattern.Point to note that the transaction management responsibility has shifted to the API façade The client has to only deal with one resource and one pure REST call.What I have not shown here is that the API façade also can do a bunch of things when the transaction go wrong. And at the end just throw a much simpler error back to the client.
14. We are not recommending a two phase REST API or “transactional REST APIs”
15. The Façade is a logical construct in terms of the architecture. It can be implemented by number of software components such as Application servers, databases, API management & exposure layer, analytics and so on. The good news is that the Façade Layer does not need to rebuild all the existing capabilities. The API Service Layer is a Façade on top of the existing capabilities. I wanted to make it clear that we show this layer as a single component – but that is just a logical representation.
16. If the API provider has EAI style two phase interfaces – using this pattern those can be re-used for exposing through the edge of the enterprise for the partners and consumers outside the organization.Backend does not need to changeOff-late we are seeing that the API programs are also opening up internal integration opportunities. Remember the “eat your own dog food” phrase? So even internal consumers who prefers REST over EAI should be able to consume the services through this pattern.
17. The second benefit is ease of use. Once we are truly REST it is much easier for the consumer to use an APIThe client deals with one resource at a time, instead of attempting to be a transaction manager of a sort.The responsibilities of transaction management if at all, is deferred to the API Façade.I am not even highlighting the other standard benefits of moving the composition responsibilities into the Façade – lower network calls from device, lower processing and all that. But let us look at the transaction management angle
18. This is an extended example of the same pattern – Here the api façade is responsible for coordinating a distributed transaction. However exposes only a single REST resource for the client.So the API façade takes care of the transaction roll back and compensation scenarios as well.Instead of looking for a "transaction protocol" over REST and HTTP, we should consider a resource that is acting as a coordinator. The client can then ask that coordinator resource do manage changes across those other resources atomically or in whatever manner makes sense for the application. The façade exposes the resource coordinators as REST resources themselvesAs far as the client is concerned, it is not aware of any distributed transaction protocol. There more complexities than just transaction management The backends may require security protocols that are not expensive for an AppThere may be rules associated with transaction timeout, rollback that the Façade can take care of
19. If we had exposed two phase API through the API Façade the Façade layer then had to maintain resource lock and resource stateThis leads to better performance and scalability of the Façade layer itself.Being freed from client specific state management the Façade layer can scale well.
20. What do we give up while taking this approach?If the use case really warrants a reliable kind of transaction management – REST may not be a good choice. But there are some examples are coming up on exposing REST APIs with transactional behaviour..
21. This is still a semantics – to support REST format transaction – The detail is in implementation and real world use casesThat is something that still can be brainstormed. With this food for thought I will conclude