[mapguide-internals] RESTful Ramblings of a Restless Lunatic

[Jason Birch]

RESTful is whatever we want it to be (as far as URL patterns go) :)  We just have to stick to the principles.  Which reminds me, I have to steal that book from my cellmate and make sure that my understanding of REST gets along with the definitive source.
 
I think that my preference would be to keep everything in the /path/notation, but we could choose to adopt a convention where the resource is specified /with/the/path, and restrictive parameters are ?specified&in&the&qstring.  This is a bit confusing because resource lists (such as /library/ ) and resources (such as session/maps/mymap.png - or whatever Bob used for this ) can both have limiting parameters.  I guess... the query terms are only applied to the last item in the path, whether resource list or resource.  That fits with current HTML behaviour.
 
Hmm.  In the second case it will be a fun exercise deciding between queries that modify the resource on the server (PUT requests) and resources that return a restricted representation of the resource without modifying it (GET requests).  Both will return the resource, whether modified or not, with appropriate HTTP code.
 
I do like the mixed notation a bit though, because otherwise how do you disambiguate between /Library/FeatureSource to get all feature sources, and /Library/FeatureSource to get the contents of a folder called FeatureSource?  Would you need some kind of illegal-in-library character to indicate the first case?  Gahhh.  Can't we just make /Library return top level links, and require the client to follow links to explore the entire structure?  I think this may be more restful/web-like than returning the entire website in one query... 
 
Paul, how to specify the content type is up for discussion.  Doing some more thinking about representations...  I would really like to honour Accepts headers in the HTTP envelope, with a fallback of just specifying the content type as a file extension (.xml, .html, .json).  FeatureServer goes a step farther and also allows a query string parameter of format=xml or whatever, but I'm not sure that I see the value in that.
 
I am pretty sure that multiple resources of the same name but different types are allowed on the same level in the Library, so we're stuck with .FeatureSource, etc, if we use the pattern that Bob has proposed.
 
I have to find some time to look at that page and think some more...  It's considerably different from the take that Haris took on it, and it is important to get right.
 
Selection.... hard one.  I guess there can only be one selection per runtime map?  So making selection a sub-resource of the map would make sense.  I wonder if the same applies to other objects that we need a server-side knowledge of.
 
We are also going to run into a bit of a thorny situation with spatial selects and things like layer state representations.  Some geometry filters and layer lists will be larger than the GET max string length.  I'd really like to avoid overloading POST for these if we can, but the only way I can see of allowing this would be to turn this kind of item into its own resource, and then referencing it by URL in the map GET request.
 
Ouch, my head is hurting.
 
Jason

________________________________

From: mapguide-internals-bounces at lists.osgeo.org on behalf of Paul Spencer
Sent: Wed 2007-10-03 7:17 PM
To: MapGuide Internals Mail List
Subject: Re: [mapguide-internals] RESTful Ramblings of a Restless Lunatic



I haven't had time to read this in detail, nor do I understand how to 
craft RESTful interfaces yet.  I have a specific question about 
enumeration, please feel free to tell me I don't know what the hell 
I'm talking about :)

1) I don't understand how the url gets built with parameters in a 
RESTful approach, can you provide an example of what the url would 
look like?

2) Is it RESTful to craft the numerate resources as follows:

GET /Library/

returns all resources at all depths below /Library

GET /Libary/n

returns the content n levels deep

GET /Libary/FeatureSource
GET /Library/FeatureSource/n ... or GET /Library/n/FeatureSource

returns only feature sources?

Um, if the above is useful then how do we request the enumeration to 
come back in .xml, .json etc?  By just appending /<content type> to 
the end?

Next question:  Is it possible to have two different resource types 
with the same name in the same folder?  IE

/Library/Parks.FeatureSource
/Library/Parks.LayerDefinition

If not, then what would the impact be of changing the various calls 
to drop the type specifier?

Cheers

Paul

On 3-Oct-07, at 3:55 PM, Robert Bray wrote:

> All,
>
> I left FOSS4G last week somewhat pumped after seeing the talk Haris 
> gave demonstrating his RESTful Web Service client. So I went out 
> this weekend  purchased the O'Reilly RESTful Web Services book and 
> read it mostly from cover to cover. That of course left me 
> pondering what a RESTful interface to MapGuide should look like, so 
> I spent a couple of hours hacking the following (still incomplete) 
> proposal together:
>
> http://trac.osgeo.org/mapguide/wiki/RESTfulWebServices
>
> I approached this somewhat differently than Haris did, at this 
> point it is up to you to decide whether that is bad or good. 
> However I think my approach is pretty clean while exposing all of 
> the capabilities of MapGuide in a RESTful manner.
>
> Feel free to either discuss this here on the list or add your 
> comments to the Wiki page (or both).
>
> Bob
> _______________________________________________
> mapguide-internals mailing list
> mapguide-internals at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/mapguide-internals

+-----------------------------------------------------------------+
|Paul Spencer                          pspencer at dmsolutions.ca    |
+-----------------------------------------------------------------+
|Chief Technology Officer                                         |
|DM Solutions Group Inc                http://www.dmsolutions.ca/ |
+-----------------------------------------------------------------+





_______________________________________________
mapguide-internals mailing list
mapguide-internals at lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/mapguide-internals