Search code examples
restspring-rest

Which REST command to use for receiving data from payload, manipulating it, and returning the result?

I am really new to REST and that kinda stuff. I want to create a small service (using Java Spring - also new to me), which should resize an image in a few different ways. Currently, I have 0 clue on which REST command I should use for this.

This is how I imagined my API to work:

  1. I send a request containing the following information:
  • Original image (from client)
  • new width + new height
  • sizing strategy (nearest neighbor ...)
  1. Server returns the new resized image

I am having trouble understanding which REST command I should use (all the information I could find was regarding storing data on the server).

I don't want to store any images or return any stored images. I just want to manipulate the image from the request and return it.

If you need more information, let me know.

Solution

  • I don't want to store any images or return any stored images. I just want to manipulate the image from the request and return it.

    HTTP doesn't have a great answer for this today.

    HTTP is an application protocol, whose application domain is the transfer of documents over a network -- Webber, 2011

    The semantics of an HTTP Server are very closely analogous to those of a document store - we ask for copies of documents (GET), or we ask that a server's copy of a document be edited (POST,PUT,PATCH,DELETE....).

    Of the registered HTTP methods, there isn't a good fit for an effectively read only request with a payload.

    Which leaves you with one of the following options

    • You can use a standard method in a non standard way, and accept responsibility for the consequences
    • You can use a non standard method
    • You can define a new method, and register it, working through the standardization process and driving adoption
    • You can use POST.

    POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding, 2009

    I am having trouble understanding how I can put an image and other information in a single payload (maybe as bytes?)

    Consider how you might achieve that on the world wide web.

    You would probably have an HTML form, with an input control (type="file") that allows the operator to specify which file to use, and additional input controls that collect other information of interest. The description of the form might include default values pre-loaded into the input controls, or lists of options, and so on. When the user submits the form, the web browser's implementation of standardized HTML form processing is applied to the inputs, producing an HTTP POST request with content-type multipart/form-data.

    It's very similar in appearance to an email with one or more attachments.

    At the origin server, the payload is unpacked - in effect reversing the transformation of the form inputs to their separated representations.

    The downside of POST, in this context, is that it doesn't communicate to general purpose components the fact that your handling of this request will be idempotent. So we don't get "automatically retry the request" when the network is losing messages.

    Furthermore, general purpose components are not going to be able to usefully cache the response, because they don't have a standardized method for including the request payload as part of the cache key.

    In short, POST is the best you can do with standardized methods.