restmethodsprinciples

RESTful: When is it OK to POST without creating a resource on server?

According to the REST principles, I understand that all POSTs to a server are supposed to be used to create a resource; modify something on the server. If you want to obtain information, you use GET.

But what about cases where you need to send extensive information to obtain a resource?

For example, complex search parameters that would be too long for a URL. Or, hypothetically, you'd like to send an image to be searched, like OCR or similar image comparisons.

I these cases, it seems it would be necessary to POST data to the server, but the result would not be a change, just information. POST an image, receive a list of similar images that exist on the server.

I don't want to build a REST API that violates these principles, unless they are actually not a violation.

EDIT

It seems all answers so far are correct (!): Sergio and Kay are right about the actual value of "bending the rules" when needed. But uriDium has a good point:

An image upload actually causes a change in the server: there is a new file, albeit temporary. The same can be thought about a complex search as "a document".

I guess we can consider the concept of "ephemeral" changes, "ephemeral POST", where the server is changed and produces a new ephemeral resource. In that case, for RESTful considerations, maybe this could be the following behaviors:

  1. Client: POST an ephemeral resource
  2. Server: Responds with the ephemeral resource URI AND a TTL header (?). It is un-restful to respond with something other than the resource URI -- right?
  3. Client: GET the ephemeral resource within the TTL time
  4. Server deletes resource after TTL

I would consider responding with full ephemeral resource on step 2 and concluding the interaction there, just for rebelliousness :-)

Solution

  • When technical constraints (e.g. using HTTP get and the max size query string for a base64 encoded limit of 2048) obstructs you from adding business value (the need to be able to compare or search for an image in your service) due to architectural approaches (RESTful webservice) I would say you can break some rule or principle you are trying to uphold.

    Most important thing is that your clients can reasonably guess how your API behaves. Exceptions like your image search using POST without creating resource can be documented explicitly for them to be aware.