Direct API integration recommendations

Below are a few common alternatives for how to integrate with a our API. Depending on the requirements in the project, some of these, variations of them, or totally different alternatives not listed here might fit better than others. All alternatives have pros and cons and choosing how to integrate should be discussed with us before implementation starts, as the choice might have unexpected side effects.

Definitions:

Front-end
- The UI that the user interacts with and the client code running on the user's local machine responsible for updating the UI. Typically running and presented in a web browser. Responsible for receiving actions from the user and making requests to the back-end based on those actions.
- Example: A webshop showing article data provided by the back-end, with a virtual shopping cart with prices calculated by us.
Back-end
- An API used to receive data from and provide data to the front-end. The response data sent to the front-end can be pure data (e.g. json) or it can contain generated UI (e.g. html). The back-end is also responsible for making requests to our API's where necessary.
- Example: A web service with methods for providing data to show (images, descriptions) and methods for modifying the user's virtual shopping cart.
Our API
- One or more of our direct APIs, running in the cloud or on-premise. This API serves as a "back-end for the back-end", getting data to and from our systems.
- Example: POS API ItemSale with methods for modifying the shopping cart and recalculating the prices using the same price rules that exist in the physical stores.

Alternative 1 - Synchronous requests

Requests are made synchronous to the back-end, which makes necessary requests to our APIs synchronously before returning the result to the front-end.
Easy to implement.
Makes sure data is synchronized to/from our systems successfully before any result is shown to the user.
May appear slow for the user, depending on the response time and number of API calls involved.

$title Alt. 1: Synchronous requests participant Front-end as Frontend participant Back-end as Backend participant Our API Frontend->+Backend: API request Backend->+Our API: API request Our API-->-Backend: Backend-->-Frontend: Synchronous response with\ndata from Our API note over Frontend UI is only updated when the synchronous call has completed with all data. end note$

Alternative 2 - Delayed synchronous requests

Requests are made synchronous to the back-end, which responds without making any requests to us. The more requests that are done before synchronizing the data with us, the more out of sync the two systems get.
To present data that is in sync, the front-end makes a new request to the back-end, which syncs the data from the previous requests with us before returning the result to the front-end.
Easy to implement.
Useful when it is not necessary to show data from us in the UI until a certain step in the process.
The step where data is requested from us might require many API requests to sync all previous user actions between back-end and us, which might increase response time significantly for this step.

$title Alt. 2: Delayed synchronous request participant Front-end as Frontend participant Back-end as Backend participant Our API Frontend->+Backend: API request Backend-->-Frontend: note over Frontend UI is updated with data from front-end end note note over Frontend Later, when UI need to be updated with data from us... end note Frontend->+Backend: API request Backend->+Our API: API request Our API-->-Backend: Backend-->-Frontend: Synchronous response with\ndata from us note over Frontend UI is updated with data from both back-end and us end note$

Alternative 3 - Asynchronous between back-end and us

Requests are made synchronous to the back-end where data from the request is put on a queue for processing, before returning data available in the back-end to the UI.
Request data is then dequeued by a background job and used to call our API. The front-end may use some polling mechanism to ask the back-end for updated data from us, which is returned to the UI after the background job has completed.
More complex implementation.
Short response time before the UI is updated with some data.
The data shown may be incomplete or incorrect until the data from us arrives to the front-end. The user can also navigate away and never get shown the complete data.

$title Alt. 3: Asynchronous between back-end and our API participant Front-end as Frontend participant Back-end as Backend participant Our API Frontend->+Backend: API request note right of Backend: Enqueue request data Backend-->-Frontend: Response note over Frontend UI is updated with only data from back-end. end note note over Backend: Dequeue request data\nin background job Backend->+Our API: API request Frontend->+Backend: Poll for updated data Our API-->-Backend: Response Backend->-Frontend: Response with updated\ndata from us note over Frontend UI is updated with data from both back-end and us end note$

Alternative 4 - Asynchronous between front-end and back-end

Requests are made asynchronous to the back-end and the user can continue to navigate the UI without waiting for a response. The back-end makes the necessary requests to our API and returns the result to the front-end, which updates the UI with the new data.
Implementation complexity depends on the existing front-end architecture and available frameworks.
Practically no wait time for the user before it is possible to continue with other actions.
Suitable for front-ends built with a framework for asynchronous operations already in place.
No real data besides the data already available in the front-end is shown before the request to back-end and our API has completed.

$title Alt. 4: Asynchronous between front-end and back-end participant Front-end as Frontend participant Back-end as Backend participant Our API Frontend->>+Backend: Async API request note over Frontend UI does not wait for response, user can continue to navigate the page without any new data. end note Backend->+Our API: API request Our API-->-Backend: Response Backend->-Frontend: Response with updated\ndata from us note over Frontend UI is updated with data from both back-end and us end note$

Alternative 5 - Not integrated with UI

Requests to us are not integrated with the front-end at all. Instead, it acts as a way of synchronizing or importing data to us at a later point in time.
Relatively easy to implement.
Response time only depends on back-end.
Features requiring online validation against our API are not available.
Data shown in UI may be incomplete or incorrect, since it is not updated with data from us online.
Error handling can get complex, since everything can be completed in the front- and back-end without verifying anything against data in our systems.

$title Alt. 5: Not integrated with UI participant Front-end as Frontend participant Back-end as Backend participant Our API Frontend->+Backend: API request note right of Backend: Enqueue request data Backend-->-Frontend: Response note over Frontend UI is updated with only data from back-end end note note over Backend: Later:\nDequeue request data\nin background job Backend->+Our API: API request Our API->Backend: Response note over Backend: Backend is updated with\ndata from us$