Does it make sense to use both query and body parameters in a POST request for a REST API?

Question

I have a resource that essentially requires another resource as input data for creation. For example:

POST /v1/NewResource
body: {InputResource}

The interesting thing, however, is that creation of the NewResource is expensive, and the resource itself is transient (not persisted). Some consumers may only need part of the resource. So, I really have two input parameters: the data required to do the creation, and then processing instructions from the consumer to control how much work actually gets done.

I see two paths (at least):

POST /v1/NewResource?detailLevel=base|full
body: {InputResource}

vs

POST /v1/NewResource
body: {Request.detailLevel and Request.InputResource}

Is the first one even an option? Anyone have any preferences/experience either way? There's a certain amount of elegance in having the payload be just the data needed and separating from the processing instructions. I realize there's no right or wrong answer here, just curious on the thoughts of the community.

Messenia

Answer 1

Mixing URI queries and content looks like valid HTTP, because the specification doesn't state that they are mutually exclusive in a http server application that accepts POST requests.

RFC 3986 defines http query strings as a uri part that works as a non-hierarchical way of locating a resource. However, RESTful architecture generally doesn't prescribe URI schemes to work in a very specific way, instead focusing more on satisfying properties like cacheability, resource design and idempotence, and less on how resources are located.

I would rather go with the first path, given the detailLevel is not exactly part of the resource itself.

Indra

Answer 2

There is actually no right or wrong regarding REST and URI design. It boils down to personal preferences actually. The semantics of a POST payload is completely up to the server. This means that it is totally up to you how partial or full data has to be distinguished from each other and/or processed by the server.

You therefore have a couple of routes you could go:

• Keep flag wheter the body payload represents full or partial information in the body
• Send the information regarding full or partial data via the URI
• As the information about the content may be considered as metadata describing the body further you may introduce a new HTTP header that flags the content as full or partial
• Create own content types for each payload type

In regards to RESTfulness I'd opt for passing this information either as header or even as own content type which you can negotiate about. That way you neither pollute the actual payload with meta information nor have to expose metadata in URIs.

As introducing new custom content types usually takes some time and effort though, probably going for a custom header value is the easier and faster solution.

Distillery