Synchronous or Asynchronous Invocation

Synchronous calls are calls that implement blocking behaviour: the caller will wait and no result or status update will be provided until either the API is ready to return the result or an error occurs.

Asynchronous calls on the other hand, return a result immediately. This intermediate result provides a way for the caller to receive updates on the status of the initiating request, while that request is being handled in the background. It also points to the location where the data or error will arrive when the request completes successfully or due to an error.

Which one should I use?

You should always default to the asynchronous invocation. The synchronous functionality is only meant to be used for the smallest of exports and may not be available as the Orgvue API evolves in time.

While a direct result might be handy, due to timeouts enforced in our backend a synchronous call will receive a timeout response if it has not completed after a short duration, currently measured in seconds. Attempting to call the synchronous endpoint again is guaranteed to fail. In a scenario like this your response data size is too big for our infrastructure to handle using the synchronous pattern, and your export will always fail and result in a timeout.