Should asynchronous requests to a RESTful API have a separate URI?

Question

Consider a web API with a method that takes a long time. The client can either make a synchronous request and wait for the response, or make an asynchronous request and receive the standard 202 Accepted response and a status link.

Under RESTful semantics, should these two options exists as two separate URIs, or should they be the same URI with an option for asynchronicity in the header parameters?

Answer 1

They dont necessarily need to have seperate URLs. It is up to you how your RESTful service operates and responds. A request is defined by:

1. Request Type
2. URL (including params)
3. Headers
4. Payload

Standards exist on the Request Type (e.g. PUT vs POST) and some of the Headers (e.g. Caching). The payload format can also be defined by the Content-Type headers. However, there are no particular REST related rules which say you must use some URL structure. Obviously it needs to be a valid URL but it's structure is entirely up to you as the service developer.

If you want to give the choice to the caller whether to process it synchronously or asynchronously, I would go for different URLs for clarity.

e.g.

• /some/dir/service1?process=async
• /some/dir/service1?process=sync

Note: I am using forward slashes here to denote pseudo directory names for clarity reasons, but even this is not technically a necessity.

You can also use custom headers if you want, but you need to define the API yourself.

If you want to make the async/sync choice on the server side (maybe based on current server load), you could implement both in a single url. You should make sure that your API has clear documentation so that developers are aware of both response formats.