[Geoserver-devel] rest resources and discovery

GeoServer GeoServer Developer
1

Last week I sent out an email about some feedback I got on the geo-web-rest mailing list. So I set out to implement a "discovery document" as specified here:

http://xrds-simple.net/core/1.0/

My first thought was to more or less do what the IndexRestlet does, generate the document from registered routes, however I am finding it a bit lacking for what I need. While I could apply the same heuristic of only including routes that do not contain any variables, I think it might be useful to have something a bit more explicit. Especially if we adopt the URI template stuff that the opensocial stuff uses:

http://bitworking.org/news/URI_Templates

Also with the above approach there is no great way to figure out what the accepted media types of formats are.

So my thought is to instead add a sort of marker interface called "Discoverable". It would look something like this:

interface Discoverable {

   String getType();

   String getURI();

   List<MediaType> getMediaTypes();

}

The uri property may be unnecessary as it could be derived from the route mapping. But the idea is that restlets that are "discoverable" would implement this interface.

Thoughts?

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

2

On Mon, 2009-02-16 at 18:41 -0700, Justin Deoliveira wrote:

Last week I sent out an email about some feedback I got on the
geo-web-rest mailing list. So I set out to implement a "discovery
document" as specified here:

http://xrds-simple.net/core/1.0/

My first thought was to more or less do what the IndexRestlet does,
generate the document from registered routes, however I am finding it a
bit lacking for what I need. While I could apply the same heuristic of
only including routes that do not contain any variables, I think it
might be useful to have something a bit more explicit. Especially if we
adopt the URI template stuff that the opensocial stuff uses:

http://bitworking.org/news/URI_Templates

Also with the above approach there is no great way to figure out what
the accepted media types of formats are.

So my thought is to instead add a sort of marker interface called
"Discoverable". It would look something like this:

interface Discoverable {

   String getType();

   String getURI();

   List<MediaType> getMediaTypes();

}

The uri property may be unnecessary as it could be derived from the
route mapping. But the idea is that restlets that are "discoverable"
would implement this interface.

Thoughts?

Advertising the URI's available from a particular rest-savvy GeoServer
instance sounds quite useful for developers/troubleshooters, but I am
having some trouble working out what a client for this sort of thing
would look like. I guess a search engine that automatically works out
keyword searches based on these URI templates (like "workspace:topp" or
"store:states") would be doable and useful. Are there any other
examples of a client out there? (I'm just curious, more rigorous
service advertising gets a +1 from me).

wrt the Discoverable interface:
1) perhaps it could fully describe a rest endpoint, so that we no longer
need the RESTMapping class? I suspect it would be useful to keep that
sort of metadata all bundled together, rather than keeping getMediaTypes
in a different place from getURI. Is there a strong case for 'hidden'
restlets (ie, Restlet subclasses that do not implement Discoverable)?

2) What is getType() vs. getMediaTypes()? Would a ServiceType enum be
more suitable than a String (assuming the 'type' refers to some sort of
classification of restful services)?

--
David Winslow
OpenGeo - http://opengeo.org/

3

Advertising the URI's available from a particular rest-savvy GeoServer
instance sounds quite useful for developers/troubleshooters, but I am
having some trouble working out what a client for this sort of thing
would look like. I guess a search engine that automatically works out
keyword searches based on these URI templates (like "workspace:topp" or
"store:states") would be doable and useful. Are there any other
examples of a client out there? (I'm just curious, more rigorous
service advertising gets a +1 from me).

I think the main idea is putting the onus on the server to publish the URI structure, rather than have the client rely on a particular structure. Sort of the same function that a capabilities document serves for OGC services. It also gives us a bit of freedom to change the uri structure if we really push clients to "discover" the uris available via the discovery doc.

wrt the Discoverable interface: 1) perhaps it could fully describe a rest endpoint, so that we no longer
need the RESTMapping class? I suspect it would be useful to keep that
sort of metadata all bundled together, rather than keeping getMediaTypes
in a different place from getURI. Is there a strong case for 'hidden'
restlets (ie, Restlet subclasses that do not implement Discoverable)?

Yeah, I thought about suping up the RESTMapping class for this purpose as to have all the endpoint metadata in one place. It would probably be the cleanest way to do it.

As for "hidden" restlets, I think i can see a case for it. For instance consider the discovery of datastores in a workspace. We may wish to just publish the uri for workspaces in the discovery document. And then the content of a workspace should contain links to all the datastores. This is more or less the approach that Haris (developer doing the MapGuide rest extensions) has adopted.

2) What is getType() vs. getMediaTypes()? Would a ServiceType enum be
more suitable than a String (assuming the 'type' refers to some sort of
classification of restful services)?

Type is a bad word for it. It is more or less just an identifier, like a namespace URI or something. The name Type is taken from the XRDS spec.

--
David Winslow
OpenGeo - http://opengeo.org/

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.