Other RESTful actions on a resource

Question

Lets say I have resource representing images

PUT /images/[id] with path -> going to create me a new image resource if already present updates my resource

POST /images/[id] -> to change or update a resource Ex., image name

DELETE /images/[id] -> this will delete my resource

GET /images/[id] -> gets me the image details

Now the actual question. what if I need to add additional actions to the images ?. Lets say the image resource will respond to a red eye reduction action or any other like crop, resize

So how these action are considered and how this should be called in restful interface ?

/images/[id]/remove_redeye

/images/[id]/crop

/images/[id]/resize

Is the above calls valid in restful interface ? I am confused about what should these action should be considered(PUT POST)?

Answer 1

"Remove redeye", "crop", and "resize" all sound like actions which "change or update a resource." They would belong in a PUT action. (I think you mixed up PUT and POST in your question, refer to the verbs listed at w3c.)

How you convey the nature of the action depends on what's being POSTed. For example, if we were talking about a form sitting on top of a database record, the POST would simply be the data for that record. It wouldn't be necessary to specify which fields are being changed because the whole object is being POSTed in its new state.

Is the whole object being POSTed in its new state in this case? Or does the object live only server-side and the interface is just sending a request for some kind of action? It sounds like the latter to me, based on the information provided.

In that case you can include in the POST some more information about the action. Keep in mind that a POST can contain key/value pairs in its data and/or a larger and more complex POST body. This body can contain XML, for example, specifying a lot more information for the server to use in processing the request. Maybe something like this:

<image id="123">
    <resize>
        <width>200</width>
        <height>200</height>
    </resize>
</image>

This could even allow multiple actions within the same request, allowing the user to try various things client-side before committing them all in a single unit of work server-side. How you'd process that or if it's even applicable in this case is up to you, of course.

Answer 2

PUT /images/[id] means to add a new resource or to fully replace an existing one.

POST means to create (/images) or to modify a resource (/images/[id]). If you create a resource, the server may return that resource for you.

For several modifying actions on the same resource (POST), I tend to use a custom header to define the kind of modification. In this case your resources

/images/[id]/remove_redeye
/images/[id]/crop
/images/[id]/resize

would translate to:

POST /images/[id] HTTP/1.1
X-RESTAction [remove_redeye|crop|resize]