Context Navigation

Changes between Version 3 and Version 4 of Future/RESTfulWebServices

Timestamp:: Mar 19, 2008, 9:57:25 PM (16 years ago)
Author:: jbirch
Comment:: Enough for tonight...

Legend:

: Unmodified
: Added
: Removed
: Modified

Future/RESTfulWebServices

-              v3
+              v4
 }}}
 To get a list of the Spatial Contexts the following might work:
+To get a list of the Spatial Contexts you would call:
 {{{
 …
 }}}
+''' (jb) QUESTION:  Does this make sense?  Shouldn't a DELETE on the class delete the class itself?'''
 To support Insert and Update operations we'll need to rely on the HTTP POST (insert) and PUT (update) methods. These operations can be defined as follows:
 …
 In both cases the HTTP request envelope must contain a property value collection that defines either the properties of the newly created feature or the properties to be updated and their new values. The collection could be in either JSON or XML format and an open question whether the URI should specify the expected type?
+''' (jb) QUESTION:  Say what?'''
 [[BR]]
 [[BR]]
 …
 The first thing we need is the ability to create a Map resource / !MgMap object.
-{{{
-POST
-.../library/MyStuff/MyMap.MapDefinition/createmap
-Optional Parameters:
-   name=<mapname>
-}}}
-{{{
-POST
-.../session/<uglysesssionid>/createmap
-Required Parameters:
-   name=<mapname>
-   srs=<srswkt>
-   envelope=x1,y1,x2,y2
-}}}
-''' (jb) ALTERNATIVE:  Unless you are going to be storing the map in those locations, I would prefer to see something like the following'''
 {{{
 …
   MapDefinition=http://example.org/mapguide/rest/library/MyStuff/MyMap.MapDefinition
 }}}
-and
 {{{
 …
 }}}
+''' (jb) ALTERNATIVE ENDS'''
+The first creates a new map from the Map Definition resource identified in the URI. The later creates an empty map with the specified name, coordinate system, and extent. Now that we have a map, we need some way to render the map (with and without selection), the dynamic overlay (with and without selection), and base map tiles.
+{{{
+GET
+.../session/<uglysesssionid>/MyMap.Map/image.png [or .jpg or .gif]
+And for server-assigned resource naming (e.g. need a unique resource to ensure no collisions):
+{{{
+POST
+.../services/createmap
+Required Parameters:
+  session=<uglysesssionid>
+  name=<mapname/
+  srs=<srswkt>
+  envelope=x1,y1,x2,y2
+}}}
+All of these, of course, would return a "201 Created" response code, and the would reply with the elements specified in section 10 of the HTTP 1.1 spec.  This includes a pointer to the created resource, which is particularly important in the latter case.
+Now that we have a map, we need some way to render the map (with and without selection), the dynamic overlay (with and without selection), and base map tiles.  These rendering calls support media types of JPG, PNG, and GIF, and we need some way of specifying PNG24 or PNG8.
+''' (jb) How to do this with no separate MIME type? Do we need to use a format override?  Are there browsers that need to have an extension for the image?  And again, we run into not knowing what resource are available under the meta "MyMap.Map" resource; we need a way to enumerate the options.'''
+{{{
+GET
+.../session/<uglysesssionid>/MyMap.Map/image
 Optional Parameters:
    <Big list of them from RenderingService::RenderMap>
+POST
+.../session/<uglysesssionid>/MyMap.Map/image.png [or .jpg or .gif]
+}}}
+{{{
+POST
+.../session/<uglysesssionid>/MyMap.Map/image
 Optional Parameters:
    <Big list of them from RenderingService::RenderMap>
 }}}
 The first one would render a single image of the map (all visible layers including base map) using the current state of the map from the session. The second provides a way to update the map state stored in the session and return a new image in a single shot. In the HTTP POST method case the post data is expected to contain a list of commands that would alter the map state, e.g. turn on these layers, turn off those layers, set the new center to this, etc.
+[[BR]]
+[[BR]]
 So what about support for tiled maps with dynamic overlays.
+{{{
+GET
+.../session/<uglysesssionid>/MyMap.Map/overlayimage.png [or .jpg or .gif]
+{{{
+GET
+.../session/<uglysesssionid>/MyMap.Map/overlayimage
 Optional Parameters:
    <List of them from RenderingService::RenderDynamicOverlay>
+POST
+.../session/<uglysesssionid>/MyMap.Map/overlayimage.png [or .jpg or .gif]
+}}}
+{{{
+POST
+.../session/<uglysesssionid>/MyMap.Map/overlayimage
 Optional Parameters:
    <List of them from RenderingService::RenderDynamicOverlay>
+}}}
+{{{
 GET
 .../library/MyStuff/MyMap.MapDefinition/basetileimage/<baselayergroupname>/<scaleindex>/<tilecolumn>,<tilerow>
 }}}
+As with the normal map image delivery, the HTTP POST form of /overlayimage can include a set of commands for altering the state of the map  object prior to rendering and returning the image. Note that base tile image access works based on a the Map Definition, not the runtime Map. That is because !MapGuide caches base map tiles based on the groups within a Map Definition, not on a per user basis.
+[[BR]]
+[[BR]]
+To build a cool client application, we need information about the map, the layers, the layer groups, etc. The next set of operations is designed to return an informational representation of map that can be used to create a compelling user interface.
+{{{
+GET
+.../session/<uglysesssionid>/MyMap.Map.xml [or .json]
+GET
+.../session/<uglysesssionid>/MyMap.Map/layers.xml [or .json]
+GET
+.../session/<uglysesssionid>/MyMap.Map/layers/<layername>.xml [or .json]
+GET
+.../session/<uglysesssionid>/MyMap.Map/layergroups.xml [or .json]
+GET
+.../session/<uglysesssionid>/MyMap.Map/layergroups/<layergroupname>.xml [or .json]
+}}}
+The output of these needs some thought, but basically would encapsulate the properties found in the !MgMap, !MgLayer, and !MgLayerGroup objects in the Web API. To complete this we need to include some way to generate a icons for the legend.
+{{{
+GET
+.../library/MyStuff/MyLayer.LayerDefinition/legendicon/<mapscale>/<geomtype>/<themecat>.png [or .jpg or .gif]
+As with the normal map image delivery, the HTTP POST form of /overlayimage can include a set of commands for altering the state of the map object prior to rendering and returning the image. Note that base tile image access works based on a the Map Definition, not the runtime Map. That is because !MapGuide caches base map tiles based on the groups within a Map Definition, not on a per user basis.
+''' (jb) COMMENT:  For the /basetileimage calls, it is critical that we support all standard HTTP caching headers.  This means checking state of the underlying tile; does this require new APIs for the tile service to return properties of the existing tile when not generating fresh? '''
+To build a cool client application, we need information about the map, the layers, the layer groups, etc. The next set of operations is designed to return an informational representation of map that can be used to create a compelling user interface.  These could be in JSON or XML.
+{{{
+GET
+.../session/<uglysesssionid>/MyMap.Map
+GET
+.../session/<uglysesssionid>/MyMap.Map/layers
+GET
+.../session/<uglysesssionid>/MyMap.Map/layers/<layername>
+GET
+.../session/<uglysesssionid>/MyMap.Map/layergroups
+GET
+.../session/<uglysesssionid>/MyMap.Map/layergroups/<layergroupname>
+}}}
+The output of these needs some thought, but basically would encapsulate the properties found in the !MgMap, !MgLayer, and !MgLayerGroup objects in the Web API. To complete this we need to include some way to generate a icons for the legend (these would return PNG8, PNG24, GIF, or JPG images)
+{{{
+GET
+.../library/MyStuff/MyLayer.LayerDefinition/legendicon/<mapscale>/<geomtype>/<themecat>
 Optional Parameters:
 …
    height=<desiredimageheight>
 }}}
+Now of course no mapping client is complete without some way to interact with and query the features displayed on the map. The !MapGuide Web API includes the !MgRenderingService::!QueryFeatures APIs for this and I propose the following RESTful representation:
+{{{
+GET
+.../session/<uglysesssionid>/MyMap.Map/features.xml [or .json]
+Now of course no mapping client is complete without some way to interact with and query the features displayed on the map. The !MapGuide Web API includes the !MgRenderingService::!QueryFeatures APIs which could be exposed RESTfully as:
+{{{
+GET
+.../session/<uglysesssionid>/MyMap.Map/features
 Optional (but highly recommended) Parameters:
 …
    maxFeatures=<maxdesiredfeatures>
 }}}
 More parameters are probably needed here, but you get the idea.
+''' (jb) COMMENT:  Some services have suggested storing the spatial filter feature as its own resource, and just refering to it in the GET.  This would prevent problems with overflowing the GET max size'''
 [[BR]]
 [[BR]]
 …
 [[BR]]
 [[BR]]
+[[BR]]
+'''Note:''' Within all of this the handling of selection is bugging me. We need to think about that some more and figure out what is the right way of handling selection RESTfully.
+[[BR]]
+''' (rb) Note: Within all of this the handling of selection is bugging me. We need to think about that some more and figure out what is the right way of handling selection RESTfully. '''
+[[BR]]
 == Other Necessary Stuff ==
+We need some way for an application to create a session. By simply support a POST to /session as follows we can meet that requirement.
+We need some way for an application to create a session. We can do that with a POST to /session as follows.
 {{{
 POST
 .../session
 }}}
+There is no required HTTP request envelope and the return envelope would simply contain the newly created session URI, e.g. http://somemgsite.org/mapguide/rest/session/<newuglysessionid>/.
+[[BR]]
+[[BR]]
+[[BR]]
+There is no required HTTP request envelope and the return envelope would simply contain the newly created session URI, e.g. http://somemgsite.org/mapguide/rest/session/<newuglysessionid>/ along with a 201 header.
 = Security, Authentication, and Access Control =
+TBD
+This is all handled by native HTTP authentication.  If generic service endpoints are required to create users and associate users with roles/groups, then these can be created as required.  Access control is handled through modification of the resource headers.