Most of the objects in the Mine implementation are “Things” – ie: a series of key=value pairs which are bundled together under a numeric identifier, which have a Class and associated methods that operate on them.

For reasons of security and sheer implementability, “Things” may not be updated under the ReST CRUD scheme; to recap ReST you are allowed four “CRUD” operations against a URL which represents an object:

…but the one that gives problems is UPDATE since the presumption is that you will atomically replace an old Thing with a new thing, much as:

mv new.jpg current.jpg

…might work in a filesystem; you are swapping one bunch of bytes for another one; but Things are complex structures with some bits you can poke, and other bits you cannot. Merely splatting them with replacement data would be painful.

Amongst the other problems with this is that “Update” is usually mapped to the HTTP-PUT method, which is badly implemented in web browsers and actually I think is below the tipping point – ie: it’s so badly implemented that ReSTful people work around it rather than get it fixed. Standard Perl::CGI for instance, does not support it.

The way I have gotten around this is slight but elegant piece of doublethink; I have implemented a ReST interface atop each Thing object, to access its key=value pairs:

…and then realising that object 42 now must exist for this trick to work at all, and that there is no point in having CREATE “choose” a key name for you – predefined variable names do not fit the ReST-CREATE model – then the key/CREATE and key/UPDATE operations are otherwise functionally identical (ie: they poke the values of keys) and therefore the latter can be dropped. Also key/CREATE is cooler, since it can poke multiple keys at the same time.

Further, that means key/CREATE is functionally identical to Thing/UPDATE so that can be dropped, too.

So all that is necessary is to mentally “rebrand” the key/CREATE operation as the Thing/UPDATE operation, and a whole pile of UPDATE operations go out of the window.

So now there is only 1 ReST-UPDATE operation that remains in the Mine – down from 11 – and that is the “update of auxilliary data”, for example replacing one JPEG that is associated with object 42, with a different JPEG.

To me this is a straight swap of one blog of data for another one, and so should remain as a ReST-UPDATE; but anywhere else that I have a ReST interface onto complex objects, I shall in future consider very carefully before implementing a UPDATE method.

Thanks to the unstructured nature of the content of an HTTP POST you can aggregate updates of an object’s values into a single request aimed at the object instead of the individual keys by using an xml/json object in an HTTP POST (or even just a set of key-value pairs!) and have a ReSTful server figure out where to apply them. That’s not an abuse of the ReST concept as you’re still only using the CRUD operations, just on larger objects than just strings and numbers.

ReST is a nice design direction – we’ve been doing it for a couple of years (at least our non-purist form of it at my current place of work) and it’s proved to be flexible enough to stand up to some quite diverse requirements (and it suits ExtJS single-page applications!). My only regret is that we chose to specify the representation as an additional parameter in the request (/api/object/42?rep=xml), rather than as the dot extension (/api/object/42.xml) as you have it.

* Consider implementing UPDATE for aggregations anyway, if it’s not too difficult. It will likely be useful to be able to atomically UPDATE a whole group of data in one swell foop, instead of having to individually set all those smaller pieces.

Clashes with other URL/operations in the same space, and I don’t want to get into parsing a token and then guessing what it meant to imply and/or having to forbid certain keynames / parameter names because they clash with API calls…

Love the batch-update point, I was wondering about that and you’ve helped me decide.

- alec

Leave a Reply

The Mine! Project

The Mine! project is about equipping people with tools and functionality to enable them:
• take charge of their data (content, relationships, transactions, knowledge)
• arrange (analyse, manipulate, combine, mash-up) it according to their needs and preferences and
• share it on their own terms
• whilst connected and networked on the web.

We’ve had a lot of conferences recently, and two of them yielded videos! We’re hosting them on YouTube nowadays, so they tend to come in 10-minute chapters, hopefully that won’t interfere with the message too much. First was BarCamp Antwerp, with Mathias Baert presenting in Flemish/Dutch an introduction to the Mine and Pymine: Second was Alec [...] […]

Well, it’s been ages. Too long, really, and I apologise. A lot has been going on with The Mine Project, notably Pymine development – the core codebase is being refactored and (I hate to put it like this) is almost back to the state of functionality where it was in December — however it’s [...] […]

Whenever people ask me: And how are you going to drive adoption of Mine!? My answer is: by not driving it… but by tapping into the kind of things people already do and are used to doing more and more. So a conclusion from a McKinsey article by Scott Griffith, CEO of Zipcar, describing how [...] […]