In which we go into the weeds for some REST
On the descending portion of the hype cycle now it seems that, like a guy in a "Rock Star" t-shirt, a "REST API" most likely isn't. It might be using HTTP as a uniform interface and identifying things with URIs, but then you find it provides text/xml or application/json responses with no links and out-of-band rules for teleporting (you can't call it traversing) to other parts of the API. Tight coupling like that is not what REST is about.
One that's getting very close is GeoServer's Configuration API. It has links from workspaces to datastores to layers, and a non-HTML client should in theory be able to follow them, changing the configuration state of the service in a step-by-step manner, led by the service itself, much in the same way you would through a web browser. All from one bookmarkable URI. This is what REST is about.
I say "in theory" because the GeoServer API doesn't hold water for formats other than HTML. Here's the problem: given a bookmarked URI ending in "workspaces" like http://example.com/workspaces, how does a client determine that this URI identifies a resource to which you can POST a new workspace and begin the configuration process using in-band information only? If you're working with a text/html representation of the resource, you'll be shown a form, and away you go, RESTfully. The semantics of forms, and specifically that submitting one sends data to certain URI, are defined in the text/html media type standard. A client doesn't need any out-of-band information: the form is in the representation, the semantics are specified by the standard "text/html" value of Content-Type header, both in-band. Now, if the server sends you back a text/xml response, there's no way for a client to know only from in-band information how it is to act on the response. That it's a certain type of resource (a GeoServer Workspace) because the URI ends in "workspaces" and the representation has a root <workspaces> element? That's out of band. That the bookmarked URI is a "GeoServer workspace bookmark"? That's out of band too.
AtomPub, on the other hand, holds water because the POST-ability of service resources (for creating new collections) is standardized under the media type "application/atomsvc+xml". If a client GETs a URI and that format comes back, the POST-ability is communicated, in-band. The "application/atom+xml" media type does the same for collections and entries, especially in its specification that an "edit" link tells the client via which resource it modifies entry and collection state. Standardizing on Atom and AtomPub, if you can, is therefore a good bet.
The interesting thing about REST that distinguishes itself from other styles is that interaction is driven by in-band information. Loose coupling, evolvability, and longevity are properties of a system that has the hypertext constraint. To get these properties, GeoServer and other APIs need to eliminate the out-of-band communication. Standardize on media types like HTML or Atom, mint their own media types (application/vnd.geoserver+xml or some such), or use links with standard relations in HTTP headers (aka Web Linking) and push for client support of those.
Comments
Re: In which we go into the weeds for some REST
Author: Chris Holmes
Thanks for the review Sean, our goal is to make GeoServer as RESTful as possible (indeed when we have the time we'd like to do REST feature access alternative to WFS).
Practically I'm still not sure of the best way forward. Atom does seem better than text/xml, but even if we did that wouldn't we still want to have text/xml representations of resources? Or are you advocating replacing all the text/xml responses with Atom/AtomPub?
As for application/vnd.geoserver+xml - isn't that out of band in its own way? Like developing a client against it you'd still need to know something about that format? Or you're saying it'd just be a better self-documenting one? I'd be interested in your ideas of what exactly that looks like. And again, would it replace text/xml responses?
As for Web Linking, it looks great but is it even accepted yet? Not that we're opposed to implementing a developing standard and encouraging its adoption, but I think things like feature access through REST are higher priority for us. And the idea with that is we'd just add http headers to our text/xml responses? If you want to help us you could sketch out exactly what headers we should add - I think it's pretty easy to add in extra http headers, so if it's not much of an effort we might be able to do it soon.
Re: In which we go into the weeds for some REST
Author: Allan Doyle
Chris asks "As for application/vnd.geoserver+xml - isn't that out of band in its own way? " -- That was my question, too. I was going to ask about "application/atomsvc+xml" instead.
Sean said
Isn't that only because RFC 5023 says it's POST-able? Then RFC 5023 is the out-of-band knowledge.
Re: In which we go into the weeds for some REST
Author: Sean
RFC 5023 isn't out-of-band: it and application/atomsvc+xml and application/atom+xml are part of the fabric of the web.
For a different take on the subject you should check out http://www.subbu.org/blog/2009/12/media-types-and-plumbing.
Governance of out of band semantics
Author: Rob Atkinson
There is a significant implication in using a special MIME type that is "part of the fabric" of the web to indicate how a client is supposed to interpret content, and the actions it may take as a result. This basically implies that conformant RESTful semantics are only possible within the governance framework of the web "fabric" - its not open to application domains to define semantics or behaviour of APIs.
Perhaps application API semantics have to be considered as an out of band (from REST point of view) on top of REST. I.e. REST semantics is an out-of-band part of any application API. This perhaps makes sense, because strong governance (fabric of the web) is useful in an out-of-band context, whereas private application semantics are much more problematic as out-of-band information, because they are hard to discover, formalise consistently, create and interpret.
Re: In which we go into the weeds for some REST
Author: Sean
I really must rethink what I've said about the GeoServer API not holding water after another read of Subbu's post. I've agreed with those who say "application/xml is not the media type you're looking for" (Mark Baker, Jim Webber) if you want to use web links, not XLinks. That link semantics aren't conveyed by the Atom namespace, but by the media type. While that's still my take, I should give Subbu's a try. If you stick to the minimum HTTP protocol (Atom invents a somewhat specialized one) and straight XML processing (Atom has distinctly different processing rules, like "must ignore"), application/xml might be fine. At any rate, I think you'd at least need an actual namespace for workspace and data store elements to make this hold water using application/xml.
No mistake: a configuration API is a great place to start getting into the REST style, and GeoServer is getting close to nailing it.
Re: In which we go into the weeds for some REST
Author: Sean
There's another issue in the GeoServer docs, which document a practice of interaction driven through a fixed URI hierarchy (see Fielding's 4 bullet at http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven). There's a protocol implied there that application/xml doesn't begin to hint at. Better: drive interaction through the links that are already present in GeoServer's workspace (and friends) representations. GeoServer is ready for REST in a lot of ways, but documents a contrary usage that will result in unnecessary coupling.