Asynchronous versus Synchronous Web service call

[oguimard]

Each of the GraphQL endpoints, to query the repository, can return results in synchronous or asynchronous way.

To avoid confusion, it is important to make the difference between :

• What does the endpoint return ? Synchronous/Asynchronous response
• How the endpoint is called ? Synchronous/Asynchronous call

What does the endpoint return ? 

There are in fact 2 possibles cases :

1. synchronous (response) : the endpoint returns always a response (good or bad) with the result regardless of the time it took to compute the result. The URL like this one {{server_url}}/HOPEXGraphQL/api/ITPM are synchronous. 
2. asynchronous (response) : the endpoint returns a task ID to use to recall the endpoint to get the result. The URL like this one {{server_url}}/HOPEXGraphQL/api/async/ITPM are asynchronous.

The first case : is particularly useful to get immediate results when calling the API. The drawback is that if it takes time to get a result, the caller is hanging and wait for the response. In case of response taking several seconds, timeout may occur on the network or web browser.

The second case : is particularly useful for requests that are time consuming to compute. A first call is made to the API. This call returns a x-hopex-task and a x-hopex-sessiontoken. The status code of the response will be HTTP 206 Partial response.  This information is then used to recall, in a pooling mechanism, the same endpoint until it returns 200 success. 

Steps to call the API in asynchronous way 

1. Make a first call to the async endpoint {{server_url}}/HOPEXGraphQL/api/async/ITPM request header should contain : x-hopex-context and x-hopex-wait
2. If the time to compute the query is
   1. lower than x-hopex-wait time : the API returns the x-hopex-task and x-hopex-sessiontoken in a 206 status
   2. higher than x-hopex-wait time : the API returns the body JSON response in a 200 status 
3. In case of 206 status code : make several call to the end point with in the header x-hopex-task and x-hopex-sessiontoken
   1. While you get 206 status the result is not available and the API is still computing
   2. As soon as you get 200 status the result is available in the body of the response. 

The mechanism for asynchronous call is web pooling. As of now we do not provide any webhook mechanism. 

 

How the endpoint is called ?

Regardless of the endpoint called (sync or async) each programming language has its own way to make an HTTP request.

Then HTTP request can be made via a synchronous or asynchronous call. For instance, the programming can be "stuck" and wait for the response before to proceed to the next step of the programming; or the programming can "continue" and get triggered when the response is available.

As a result you can end up in the following situation :

• A synchronous call to the synchronous endpoint
• A synchronous call to the asynchronous endpoint
• A asynchronous call to the synchronous endpoint
• A asynchronous call to the asynchronous endpoint

 

Which is the best option ?

In fact it depends on the use case. Is it a web application ? Is it a mobile app ? What is the quality of the network ? What are timeout options ? 

Asynchronous are better when the system can deal with the response at a later stage : web application, mobile app for instance.

Synchronous are better when the system needs the information to proceed to the next steps : integration with other systems for instance.