What is the best practice for building an API that takes a long time to respond?

Question

I am building an API endpoint that has to call multiple external services/DBs and I do not want my users to have to wait for this process to take place, however, the result of this process is essential for my users.

My first thought is to add the request to a queue and return immediately, then at some later time, the user can query a different endpoint for the result.

Is there a better way to go about this? Should there be a webhook response instead of asking users to query the API twice?

Answer 1

Three main ways I've seen:

1. Client sends the API request and immediately gets back a job number. The client can then send a different API request with that job number every so often (every minute or so depending upon how long the usual result takes to get) so check on the progress. On one of those checks the job will be done and the get the data.

2. Client makes awebSocket or socket.io connection. Client sends a request over that websocket/socket.io connection. Server starts working on the result. When the result is done, it is immediately sent over the webSocket/socket.io connection back to the client. The client can then keep the websocket/socket.io connection connected for other requests or close the connection.

3. Use Server-Sent events . Send, the query and then when the result is done, the server can send it back on that same connection.

I don't think there's a "best practice" among these three as each have some advantages and some other uses which may be relevant. The polling option #1 is the lowest common denominator and will work in any situation, but requires a polling strategy by the client and may have some latency (result ready before client polls).

The choices #2 and #3 are both very efficient and their general technology may have other uses also.