API question: Should requests block or run asynchronously?

[matt (Matt Holt)]

I’m stubbing out some basic API endpoints. Right now, just to start and stop instances.

To start an instance, you pass in a Caddyfile (and a server type name, if not HTTP which is the default). You get back an instance ID. To stop, you pass in an instance ID. It returns an error or 200 OK.

The question is: should API requests block? Starting and stopping instances can take several seconds. Starting, because plugins can hook into the startup process and run code; this is how certificates are obtained, which, for many sites, can take a minute or two. Stopping, because HTTP cleans up connections and that can take a few seconds.

The nice thing about blocking requests is that you get the error message returned in the response; non-blocking requests kick off the process and return a 201 Accepted immediately, but any error message just goes to the server log.

I’m personally leaning towards requests that block. (The reasoning being that you can make your request async if you want.)

(Also, these are not presumed to be high-volume endpoints…)

[abiosoft (Abiola Ibrahim)]

It can be asynchronous, in which case you’ll have to provide another endpoint to check status.

Also bear in mind that the longer the request, the higher the chance of it terminating abruptly (network errors e.t.c.).