UserPreferences

RestBenefits


This page should define benefits of the REST approach to the API. Since I am a programmer and usually use XML-RPC, the given reasoning might not be every facette of the stuff, I hope others will add. It might be a bit weird at first, fee free to edit and change. See it as a first brainstorming. Don't flame, edit. ;) [GeorgBauer, RefactorOk, DeleteOk]

REST has a much more document centric view on the stuff it handles. While XML-RPC is done to pass around data structures in a programming API fashion, REST is done to pass around XML source. This is the main difference between those techniques. So what do we gain if we choose REST?

The biggest - and most often reported - benefit would be that the wire format and the serialization format (the XML representation) are identical. This is not a benefit in itself, as usually the internal represention is quite different - most programs won't handle XML source internally, but will use data structures. But it allows to work in a more XML centric way.

One way would be to use standard XML techniques like XSLT transformations to work on them, using XPath to fetch elements from entries and to use DOM parsers to transfer the entries into an independend data structures. So people used to work with information in the classic sense would be allowed to use their default tools to do this, even on the API level.

Examples I can cook up would be to use the 4Suite stuff in Python to store XML entries into the persistent DOM database to use XPath and stuff to access parts of them and use all the other stuff to collect, select, aggregate the information. This would be a pure XML environment. I think this would benefit from a RESTful API, as entries wouldn't need to be translated into some other form before transmitting them.

Programmers usually think in data structures and algorithms. Information workers usually think in information representation, transformation and access. Those are quite different views. While programmers prefer some way of expressing algorithms in more imperative ways (unless the use functional programming), information workers prefer declaritive ways to work with their stuff.

Another problem is in the extensibility. Information workers would want to use extensibility in a much more free way than programmers would like. Programmers usually implement only those extensions they directly use in their program - you need some code to work with trackback information to see a need to parse the trackback stuff and create the trackback stuff.

The REST approach is much more lossless in this way, as it allways transfers the full entry, stores the full entry, retrieves the full entry. The more classic approach usually has it's database structures and only stores what is there and retrieves that, so an entry might lose elements the programmer doesn't use in his program currently.

Information workers usually take all information they can get, because their tools are implemented at a higher level - all information is available, but meaningless until they build some rules to use them. But it must be stored and be accessible nontheless, as they can't say what will be needed tomorrow (maybe tomorrow they want to set up a feed of all entries in their database which have trackback URIs connected, or use ent:topic stuff, so even though their software currently doesn't support it, they have to store it nontheless).