CODEWITHSUNDEEP
restasynchronousasp.net-web-api
Matthew Piziak
Matthew Piziak

Reputation: 3520

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

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?

Upvotes: 6

Views: 2361

Answers (2)

madarinho
madarinho

Reputation: 97

I would separate it to different URLs considering those reasons (I'm sure others will find more):

  • It will enable separating the operation to different methods, classes or even services.
  • It will be easier to cancel one of them when desired. e.g. moving all async processing from REST to messaging queue.
  • Less spaghetti inside your code.

Upvotes: 0

Phil
Phil

Reputation: 2313

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.

Upvotes: 2

Related Questions