This document discusses converting synchronous APIs to asynchronous APIs. It provides examples of synchronous and asynchronous APIs. The key problem is that synchronous behavior may be required by end users but asynchronous APIs do not support callbacks. The solution presented is to introduce an API facade that handles the synchronous to asynchronous conversion, acting as a callback host. This allows existing asynchronous backends and capabilities to be exposed via both synchronous and asynchronous API styles.
6. Webcast Series: API Facade Patterns
Episode 1
Composition
Episode 2
Session Management
Episode 3
One Phase to Two Phase Conversion
Episode 4
Synchronous to Asynchronous Conversion
7. Episode 4 : Synchronous to Asynchronous Conversion
Conversion
Problem
Solution
Benefits
Considerations
8. Problem
Conversion of asynchronous style APIs to synchronous
To enable API teams and app developers to implement and
improve their API designs and apps
9. Example of a Synchronous API
1. Request
API
Provider
2. Response
Client waits
for the response
10. Example of a Synchronous API
POST
http://example.com/smsmessaging/outbound/tel%3A%2B12345678/r
equests
{"outboundSMSMessageRequest":
{
"address":["tel:+13500000991”],
"senderAddress":"tel:12345678",
"outboundSMSTextMessage":
{
"message":"Hello World”
},
"senderName":"ACME Inc.”
}
}
11. Example of a Synchronous API
Response:
HTTP/1.1 200
{"deliveryInfo":
{
"address":"tel:+1350000991",
"deliveryStatus":"DeliveredToNetwork”
}
}
}
13. Example of an Asynchronous API
1. Request
Client API
Provider
Client does not wait
for the completion of
the process
14. Example of an Asynchronous API
1. Request
Client does not wait
for the completion API
Client
of the process Provider
2. Asynch Response
Server calls back
15. Example of an Asynchronous API
POST
http://example.com/smsmessaging/outbound/tel%3A%2B12345678/r
equests
{"outboundSMSMessageRequest":
{
"address":["tel:+13500000991”],
"senderAddress":"tel:12345678",
"outboundSMSTextMessage":
{
"message":"Hello World”
},
"senderName":"ACME Inc.”
}
"receiptRequest":
{
"notifyURL":"http://…/notifications/",
"callbackData":”12345"},
}
16. Example of an Asynchronous API
Immediate Response:
HTTP/1.1 201
{"deliveryInfo":
{
"address":"tel:+1350000991",
"deliveryStatus":"MessageWaiting”
}
}
"receiptRequest":
{
"notifyURL":"http://…/notifications/",
"callbackData":”12345"},
}
17. Example of an Asynchronous API
Asynch Call-back Response (A new request):
POST http://Client-app.example.com/notifications/
{
"deliveryInfoNotification":
{
"callbackData": "12345”,
"deliveryInfo":
{
"address":"tel:+1350000991",
"deliveryStatus":"DeliveredToNetwork"
}
}
}
25. When the Target Does not Provide a Call Back
1. Request
Client does not wait
for the completion of
API
the process Provider
2. Check Status
Client checks for the
status later
26.
27.
28. Example of the API Façade
API Façade
API
Existing Backend
Exposure &
Capabilities Server
Mgmt.
App relies on REST
34. What is a good timeout for asynch to synch conversion?
35. Do not abandon the Asynchronous APIs
• High throughput
• Lower response-time
36. Provide Choice to Developers when Possible
If you really need a synch API -
Have a synchronous variation of the same API
alongside an asynchronous variation
Hello & Good morningWelcome to the Essential API Façade Patterns WebcastToday is Episode 4 , the last one of the series and we are going to discuss Synchronous to Asynchronous Conversion Façade Pattern.Thanks for joining us today
In terms of relevant preparatory material you can checkout this fantastic community of API thinkers and doers on a google groups called API Crafthang out and feel free to share your thoughts on APIs
The slides that we are going to be presenting today, the earlier slides of the series, and all other webiner slides of the past are available on slidesharePls go to slideshare.net/apigee
This video and other videos of the webcast series will be available on youtubeWe have a youtube channel At youtube.com/apigee
I am Santanu DeyI am a senior solution architect here at Apigee – I am love to work on Integration – primarily focused on API based Integration & I love APIs
This webcast is the last one of a four part series on Essential API Façades PatternsToday we will talk about synchronous to asynchronous conversion patterns using API façade.
Each of these web cast episodes are structured in four sectionsWill take about 20 minutes.
What is the problem statement for this pattern? What is the best way convert an Asynchronous style API to synchronous REST API So that,Applications which consumes these APIs can implement the applications with ease and improved design to make the App-experincebetterFor API providers what is the right way to implement this conversion?“Conversion of Asynchronous style API to Synchronous” For REST APIs and Apps So that is our problem statement today
Let us look at an example of REST style synchronous APIA client sends a request to the server over HTTPAnd then the client will wait for the server to respond back.Processing at the client end will be blocked for the server to respond. If the server does not respond back within a given timeframe, the client will stop waiting for that response. It is a “timeout”
Let me elaborate on synchronous communication with a REST style Request / ResponseTake the example of a standard SMS API. A client application sends a short text message for a destination number to the server. This is the request. A POST request – In REST POST is used used for creating a resource in the server. For instance, SMS is the resource in this case.
If the server is able to process and complete the request the response would look like a standard HTTP success response, with 200 response code,The payload or response body would suggest that the processing was completed. The SMS delivery status as “DeliveredToNetwork” indicates that In case of error scenarios like bad number of bad request you may expect a 400 HTTP response and so on.If the response tokes too long or because HTTP is unreliable there may be occasional connection issues such as data packet drops. In such cases the client would time out. But in case of success, creating the resource.
In case of asynch API as usual the client originates a request.However it does not wait for the server to process the request and send back a response.
The service provider may send back a response, later on, in a completely different service call invocation.The callback notification is then handled by the client.. To process further.From the perspective of the client – the notification can arrive at an out of sync time. It does not halt processing for the response.
Again taking the SMS exampleThe request remains almost same. It is a post request to create the request on the server side.One important distinction here is to include the notification URL and an unique correlation id in the requestthat the response can be identified to be associated with a the original request.In stead of dynamic call back URLs it can also be based on a pre-defined contract.
Because HTTP is itself synchronous Transport, there would have to be an immediate response, though the actual process of handling the SMS may not complete. So the immediate response would be more of an acknowledgement. Here the IMMEDIATE http response would just be a HTTP 201 which means the request was created, but the processing status is shown in the delibvery status
Once the actual processing is completed. The server would respond back.Here the asynchronous response is a new call altogether. Back in to the notify URL of the client.
i.e., the use case may require the user to wait for the response for before the next action – If we do not address that aspect it would lead to loss of user experienceFor user experience issue take this example Take the example of Booking a travel ticketThen booking a hotel stay.So this case the application experience can not Here the end-user application would have to wait for completion of the processing. If we take programmatic workarounds, that may lead to the situation where it may block main flow of the programIf one tries to work around, it might lead to thread management or asynchronous tasks in the client runtime.(If supported.) Code may become difficult to maintain / manage
This is an obvious point.
For the client the it is a single requestThe API Façade makes the necessary plumbing to address the asynchronous provider.
I am going to use a UML sequence diagram to explain the responsibilities of the API Façade layer in this pattern.
Point to consider here – time out till which the Façade layer will wait for a call back.Façade layer constructs and provides the call back URL…Façade waits for the responseIMPORTANT The API Façade layer when it receives the callback – it matches with the request correlator – that takes care of matching the request with response.
What I have not shown in the previous diagram is that the API façade also waits for a time out period. When the time out fails – it responds back to the client with an error response. If the timeout is too long – the end user would have to wait too long for an API response. On the other hand if the timeout is too short in that case the target side may not be able to process the SMS delivery status within that period.
There is a variation of this pattern. Let consider another way of implementing the asynchronous pattern.In this case the target system, the API provider does not
Almost same flow like before. Except that in place of notification from the server, the consumer needs to check the status.
In this case the Façade Layer will be polling for response. Polling frequency, retries are parameters to consider in the design. SO in two cases you may error outTime outStatus obtained from server is “negative”
Ok – before concluding the solution section, quick emphasis on the implementation of the Façade.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.
It must be a better available piece of infrastructure – Can be more secure – Can be protected by security. basic auth over SSL, IP filtering, etc.If the notification was received even after time-out – it can be debugged, On security,Some information received in the call back is not necessary for the client app. Façade can hide those from client.
Logging, alerting, forwarding to another server.. Etc.SLA monitoring is another important thing to consider for asynch calls. That can be done by the Façade layer as well.
This pattern can be employed to convert inherently asynchronous transport into synchronous.1. JMS interface can be converted into HTTP/REST.
This is totally driven by user experience / requirement enforced by the use case?What is the SLA the backend is providing for the call back?Technically also it can not be infinitely long – all HTTP clients, routers, gateways and servers have reasonable timeouts defined. We should not hit on the borderline of such time lines. Most appliances have 60 to 120 seconds defined.
Apply this pattern only client-application scenarios – where having a call back is not possible..Better user experience in terms of of request processing time.Also holding the request state in a API Façade Layer is a costly use case for a mediation layer. So for a very high throughput transaction this pattern is costly.