CODEWITHSUNDEEP
rest
WayneC
WayneC

Reputation: 2560

Mix of query and form params in REST service?

We have a REST API which, for certain operations, we provide the option of asynchronous requests. For async requests, the service will return immediately with a token which can be used to query for completion, while for synchronous requests, the response will not be returned until the operation completes.

The current design for this looks something like this:

URL: PUT /api/orders/1234?async=true

Request Body: customerName=My Company&city=Dallas

Intuitively, it seems wrong to mix query and form params like this, however the query param (async) is providing options to the service call and not an attribute of the resource. That was the primary reason we did not include it in the request body.

Does this approach seem like a good design, or is there a better more "REST-y" way to accomplish the same?

Upvotes: 1

Views: 416

Answers (2)

Darrel Miller
Darrel Miller

Reputation: 142202

The Prefer header is designed to do exactly what you are trying to do. See the spec.

Upvotes: 1

user1907906
user1907906

Reputation:

An URL like this

POST /api/orders/1234?async=true

is not RESTful. Why POST? This looks like RPC over HTTP.

What are your resources? If there is some computation involved, model the computation as resources. POST to a collection of compuations to create a new one. Receive a Location header for the result of the computation.

POST /api/orders

custoerName=My Company
city=Dallas

This could return a response like:

201 Created
Location: /api/orders/1234

Then the client could GET the result:

GET /api/orders/1234

And the server would respond:

200 OK

Some result body.

How to make this asynchronouse?

You write:

however the query param (async) is providing options to the service call and not an attribute of the resource

This is plain wrong. Everything that is in the URI is used to identify the resource. REST is not about calling methods with parameters.

I recommend to always use the two-step-approach described above when modeling compuations/transactions/shopping carts as resources. Create it, retrieve it.

Upvotes: 1

Related Questions