Is it a good idea to have conditional sync/async HTTP API

Question

The api has one endpoint with some parameters. Based on these parameters I can predict how long the processing of the request would take. It can go from seconds(s) to tens of seconds.

When expected time is small, I want to make response synchronously, and return 200 upon completion.

For heavier requests I'd like to respond instantly with 202 and some id, so that client cant poll for the result

The question is - Is it a good idea to dynamically switch between sync and async based on request body?

Answer 1

This sounds like a lot of complexity for clients. If your API already requires the complexity of async operations, then it could make sense to go fully async.

But this really depends on what needs you expect clients to have.

If you want to avoid excessive status polling then it could make sense if clients provide a timeout parameter to control how long the request may be pending (from the perspective of the server, ignoring network issues).

For example, this client wants to go fully async and disables any timeouts:

> POST /tasks?timeout=0
>
> {...}

< 202 Accepted
<
< {"task": "b9b6d375-79ad-4170-9ff1-e714cba35781",
<  "status": "pending"}

(time passes)

> GET /tasks/b9b6d375-79ad-4170-9ff1-e714cba35781?timeout=0

< 200 OK
<
< {"task": "b9b6d375-79ad-4170-9ff1-e714cba35781",
<  "status": "done",
<  "result": ...}

This other client tolerates a short timeout but eventually gets an async response:

> POST /tasks?timeout=1s
>
> {...}

(1s passes)

< 202 Accepted
<
< {"task": "953c229c-9de8-48f8-b4cd-9c8dfdfdeba5",
<  "status: "pending"}

(time passes)

> GET /tasks/953c229c-9de8-48f8-b4cd-9c8dfdfdeba5?timeout=1s

(1s passes)

< 200 OK
<
< {"task": "953c229c-9de8-48f8-b4cd-9c8dfdfdeba5",
<  "status: "pending"}

(time passes)

> GET /tasks/953c229c-9de8-48f8-b4cd-9c8dfdfdeba5?timeout=1s

< 200 OK
<
< {"task": "953c229c-9de8-48f8-b4cd-9c8dfdfdeba5",
<  "status": "done",
<  "result": ...}

This other client waits for a longer timeout and gets a response for the same request:

> POST /tasks?timeout=20s

(time passes)

< 200 OK
<
< {"task": "39a2ae46-09a9-4920-a418-56272f97c9fe",
<  "status": "done",
<  "result": ...}

Maybe the API offers an option to disable async responses completely. Here is a client that does this, but eventually gets an error because the timeout was exceeded:

> POST /tasks?timeout=10s&async=false

(10s pass)

< 504 Gateway Timeout
<
< {"task": "77f6a32a-ea12-4eca-ba83-51d2d518eed1",
<  "status: "pending"}