[Decapod] RESTful API

Boyan Sheytanov boyan.sheytanov at asteasolutions.com
Tue Jan 26 14:21:27 UTC 2010

Hi Colin et al!

As I finished the client-side UI for the Fix image functionality (FLUID-3478
now resolved), I moved on to the server-side. Before writing a script for
fixing images, I thought it would be good to devise the URI API so that we
can finalize it and document it (would be useful to Thomas' team as well).
Having spent some time thinking over, reading and recalling RESTful
concepts, I am now at a fork in the road to RESTfulness.

The left path is kind of tricky - it doesn't make the application RESTful,
only makes the URLs more resource oriented (i.e. we will have DELETE
http://www.myDecapodServer.com/images/13 instead of GET
http://www.myDecapodServer.com/delete?fileIndex=13). The right road leads us
to internal peace by moving the model from the Capture component to the
server and keeping only the currently selected image in the client, thus
conforming to all REST constraints. I'm inclined to take the right turn so
here's a detailed description of where it leads:

The model is kept server-side (model = an array of items, each item having a
path to the full-sized, thumbnail, and dewarped images). Each item in the
model is the representation (in REST terms) of a resource. Each resource can
be accessed by a unique ID (the index it has in the model). The only state
kept in the client is the index of the currently selected image. Then, we
can have the following API (all of the URIs are prefixed by the server

POST /images/ - takes a new picture, generates a thumbnail, saves both to
the file system, returns an id (index in the model).
PUT /images/ - generates PDF, returns path to it.
GET /images/3 - returns the representation of an image. That is an object
with fullImage, thumbImage and fixedImage properties.
DELETE /images/3 - deletes the image at the specified index in the model.
POST /images/3 - recaptures an image, returns new representation.
PUT /images/3 - fixes image, returns new representation.

Pros - using only standard HTTP methods, all paths represent resources. Cons
- actions not intuitively mapped to methods (this is not standard CRUD as in
many RESTful applications), not easily extensible if a lot more actions come
up in the future.

Thought of something like POST /images/0/fix, etc, but didn't like it
because paths do not always represent a resource. Might reconsider it

Does any of the above make sense? I'd appreciate your answers (or questions
- I feel I didn't express my ideas well enough).


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://fluidproject.org/pipermail/fluid-work/attachments/20100126/76c3e101/attachment.html>

More information about the fluid-work mailing list