Changes between Version 2 and Version 3 of Future/RESTfulWebServices

Timestamp:

03/19/08 21:27:03 (17 years ago)

Author:

jbirch

Comment:

Gotta save more frequently...

Future/RESTfulWebServices

@@ -4 +4 @@
 
 = Overview =
-This page is a living proposal for defining a RESTful Web Service interface to !MapGuide. Most of the discussion here will center around the concepts of Resources, Addressability, and Representations (and probably some side debate about state). If you have no idea what I am talking about the O'Reilly book RESTful Web Services by Leonard Richardson and Sam Ruby is a great place to start. RESTful web services are all about using HTTP the way it was meant to be used, and as such most operations are performed using standard HTTP GET, PUT, and DELETE methods. The HTTP HEAD, OPTIONS, and POST methods also play a role, but POST in particular needs to be used carefully in order to be considered RESTful.
-
-For now lets assume the URI: http://somemgsite.org/mapguide/rest is the root of the !MapGuide RESTful web services. All subsequent URIs below will leave this part off and focus on resources and their representations.
+
+This page is a living proposal for defining a RESTful Web Service interface to !MapGuide. Most of the discussion here will center around the concepts of Resources, Addressability, and Representations (and probably some side debate about state). If you have no idea what REST is, the O'Reilly book ''RESTful Web Services'' by Leonard Richardson and Sam Ruby is a great place to start. RESTful web services are all about using HTTP the way it was meant to be used, and as such most operations are performed using standard HTTP GET, PUT, and DELETE methods. The HTTP HEAD, OPTIONS, and POST methods also play a role, but POST in particular needs to be used carefully in order to be considered RESTful.
+
+In all cases, this proposal should attempt to make the best use of the HTTP 1.1 protocol as defined in [http://www.w3.org/Protocols/rfc2616/rfc2616.html RFC 2616].
+
+= Conventions =
+
+For now lets assume the URI: !http://example.org/mapguide/rest is the root of the !MapGuide RESTful web services. All subsequent URIs below will leave this part off and focus on resources and their representations.
+
+Unless otherwise stated, you can assume that a GET returns the content of the resource, a POST creates a new resource from the HTTP body contents, a PUT replaces the contents of an existing resource with the contents of the HTTP body, and a DELETE removes the resource.  The HTTP contents returned for these requests is variable depending on what is requested, but proper HTTP response codes (200, 404, and many other relevant codes) must be issued to ensure correct behaviour of the clients.
+
+== HTTP header handling ==
+
+There are certain components of the HTTP mechanism that should be supported, but some will also require pragmatic fallbacks to ensure that the !MapGuide service works with existing applications.
+
+=== Cache-based headers ===
+
+Where possible, the rest services should take full advantage of the mechansims of the web to improve performance and reduce load.  In particular, this means things like setting headers such as ETag and Last-Modified, and responding to HTTP HEAD requests like If-Modified-Since and If-None-Match with appropriate headers and data.  See sections 13 and 14 of the HTTP spec.
+
+=== Accept / Content-Type ===
+
+It would be desirable for our rest services to support content negotiation.  For instance, if a client sends
+
+{{{
+GET /library/MyStuff/Parcels.FeatureSource/content
+Accept: application/json
+}}}
+
+Then the services would respond with a JSON-encoded version of that resource.  Unfortunately, the majority of current client applications make poor use of this mechanism, and in some cases there may be no official MIME type associated with the data we need to return, so we will also support alternate mechanisms for requesting different representations of the same resource.  For instance, the above request could also be made like this:
+
+{{{
+GET /library/MyStuff/Parcels.FeatureSource/content?f=json
+}}}
+
+or
+
+{{{
+GET /library/MyStuff/Parcels.FeatureSource/content.json
+}}}
+
+For each of the examples in this discussion, the supported types will be indicated but only the first form (without explicit type) will be shown.
+
+=== Method Overrides ===
+
+Again, we need to be pragmatic.  Although the preferred method of updating and deleting features is through the PUT and DELETE methods, these web services will also support an alternate mechanism for overloading the POST method to allow clients to work around firewalls that prohibit these methods.  This strategy is the same used by Google with GData (http://code.google.com/apis/gdata/basics.html)
+
+In cases where PUT is not supported, the client can use:
+
+{{{
+X-HTTP-Method-Override: PUT
+}}}
+
+In cases where DELETE is not supported, the client can use:
+
+{{{
+X-HTTP-Method-Override: DELETE
+}}}
+
+== Hyperlinks ==
+
+The MapGuide repository encodes resource references internally with a pseudo-URI that looks something like:
+
+{{{
+  Library://PathTo/Resource.FeatureSource
+}}}
+
+In this implementation, these "internal" hyperlinks will be transcoded to true hyperlinks to resources via the rest service.  For instance, the above would appear as:
+
+{{{
+  http://example.org/mapguide/rest/library/PathTo/Resource.FeatureSource
+}}}
+
+It is important to note that these will always be provided without hints to content type.
 
 = Resources and Representations =
-In my twisted little mind !MapGuide at its core is a storage container of Resources (or more correctly the Resource Database is the container and Resource Service is the API for accessing it). The other !MapGuide Services are a means of providing alternate representations of the resources stored in the resource database. In fact it is fairly easy to think of each Resource Type as having a number of representations, e.g. a Feature Source Definition has it's content (the resource itself), a schema, and features. If you follow and buy into that line of thinking, then the RESTful interface falls out fairly naturally. Let's start by looking at Resources themselves and the operations of Resource Service in a RESTful kind of way. Then we'll look at the different representations of each resource type and how that maps to our RESTful way of thinking.
+
+!MapGuide at its core is a storage container of Resources (or more correctly the Resource Database is the container and Resource Service is the API for accessing it). The other !MapGuide Services are a means of providing alternate representations of the resources stored in the resource database. In fact it is fairly easy to think of each Resource Type as having a number of representations, e.g. a Feature Source Definition has it's content (the resource itself), a schema, and features. If you follow and buy into that line of thinking, then the RESTful interface falls out fairly naturally. Let's start by looking at Resources themselves and the operations of Resource Service in a RESTful kind of way. Then we'll look at the different representations of each resource type and how that maps to our RESTful way of thinking.
 
 == Resources and the Resource Service ==
 
+Most of the calls in this section (apart from places where arbitrary resource data is stored) support both XML and JSON encoded results.  These can be requested using the pattern shown in the introduction of this document.
+
+''' (jb) QUESTION:  Can we provide an HTML representation of the repository as well?  This would keep us honest with hyperlinking, and make an easy tool for authenticated users to navigate the repository.  I think that a simple transcoding of the XML to HTML entities and wrapping it in an HTML body would be sufficient?'''
+
 Resource Service supports the manipulation of resource content, headers, and data. A RESTful interface to get a resource might be:
-{{{
-GET
-.../library/MyStuff/Parcels.FeatureSource/content.xml
-}}}
-In this case the XML definition of the resource comes back in the HTTP response envelope. To get the JSON representation one could use:
-{{{
-GET
-.../library/MyStuff/Parcels.FeatureSource/content.json
-}}}
-To change or create a resource the PUT operation would be used instead with the resource content in the HTTP request envelope. For example:
+
+{{{
+GET
+.../library/MyStuff/Parcels.FeatureSource/content
+}}}
+
+''' (jb) QUESTION:  Is there any way that we could have GET /library/MyStuff/Parcels.FeatureSource/ return a set of links to the header, content, and resource data (and more, such as features, covered below)?  Currently there is a gap in hyperlinking between the enumeration of MyStuff and the three components of the FeatureSource.  We don't want to break the "discoverability" of these resources.'''
+
+
+Likewise updating a header with permissions or meta data for an existing feature source would look like:
+
 {{{
 PUT
-.../library/MyStuff/Parcels.FeatureSource/content.xml
-}}}
-Likewise to get or set a resource header to update permissions or meta data would be as follows:
-{{{
-GET
-.../library/MyStuff/Parcels.FeatureSource/header.xml
-
-PUT
-.../library/MyStuff/Parcels.FeatureSource/header.xml
-}}}
-And similarly to modify resource data the URIs would be:
-{{{
-GET
+.../library/MyStuff/Parcels.FeatureSource/header
+}}}
+
+And similarly, you could create resource data as (ensuring that the media type is set in the HTTP headers):
+
+{{{
+POST
 .../library/MyStuff/Parcels.FeatureSource/data/<dataname>.<datatype>
-
-PUT
-.../library/MyStuff/Parcels.FeatureSource/data/<dataname>.<datatype>
-}}}
-Where <dataname> is the name of the data element and <datatype> is one of file, string, or stream. The actual type of the data element being stored should be specified in the media-type in the HTTP header.
-[[br]][[br]]
-Another typical operation in Resource Service is enumerating resources and resource data. At first that seems simple, just use an HTTP GET operation on a library folder. However that could easily flood the client with way too much information. The !EnumerateResources operation in Resource Service takes two parameters, depth and resource type, to limit the enumeration. We could support these through perverse URI encoding, but I think this is a better place to introduce parameters. So I propose the following:
-{{{
-GET
-.../library/MyStuff.xml
-
-Optional Parameters:
-   depth=<depth>
-   type=<resourcetype>
-}}}
-Like the other operations above we could also support /json. The depth and type parameters are optional and match those of the existing !EnumerateResources operation. Enumerating resource data is easier and would be represented as follows:
-{{{
-GET
-.../library/MyStuff/Parcels.FeatureSource/data.xml
-}}}
-So what about those session-based resources that !MapGuide is so dependent on. Well, from my perspective that is easy. You simply change the URI to address the session. For example to get layer definition content from a session the following could be used:
-{{{
-GET
-.../session/<uglysessionid>/Parcels.LayerDefinition/content.xml
-}}}
-'''TBD''' - Still need to think about how to support other Resource Service operations like Move, Copy, ApplyPackage, etc.
-[[BR]]
-[[BR]]
+}}}
+
+Where <dataname> is the name of the data element and <datatype> is one of file, string, or stream. 
+
+Another typical operation in Resource Service is enumerating resources and resource data. At first that seems simple, just use an HTTP GET operation on a library folder. However that could easily flood the client with way too much information.  The !EnumerateResources operation in Resource Service takes two optional parameters, depth and resource type, to limit the enumeration, and these can be specified as parameters:
+
+{{{
+GET
+.../library/MyStuff?depth=<depth>&type=<resourcetype>
+}}}
+
+Enumerating resource data is easier and would be represented as follows:
+
+{{{
+GET
+.../library/MyStuff/Parcels.FeatureSource/data
+}}}
+
+So what about those session-based resources that !MapGuide is so dependent on for complex long-term user interactions?  You simply apply the same logic as above to use URIs with a session prefix.  For example, to get layer definition content from a session the following could be used:
+
+{{{
+GET
+.../session/<uglysessionid>/Parcels.LayerDefinition
+}}}
+
+Apart from simple CRUD operations on resources, there are other operations that should be implemented as service endpoints.  These include things like Copy, Move, ApplyPackage, etc, that require operations on multiple resources.  For isntance, Copy must copy the resource content, header and data all in one atomic call.  These will be implemeted under their own URIs.
+
+For instance, copying a resource could be accomplished something like this:
+
+{{{
+POST
+.../services/CopyResource
+Source=http://example.com/mapguide/rest/library/MyStuff/Parcels.FeatureSource
+Destination=http://example.com/mapguide/rest/library/MyStuff/ParcelsCopy.FeatureSource
+}}}
 
 == Alternate Representations for Feature Sources ==
-Now this is where things start to get interesting. What alternate representations do we expose for Feature Sources to support the Feature Services API. We'll start with basic schema access and drill down into feature selection, update, etc. So to describe the schema of a Feature Source I would propose something like:
-{{{
-GET
-.../library/MyStuff/MyData.FeatureSource/schema.xml [or .json]
-}}}
-Want just the schema of a particular schema or even a single class? How about:
-{{{
-GET
-.../library/MyStuff/MyData.FeatureSource/schema/<schemaname>.xml [or .json]
-GET
-.../library/MyStuff/MyData.FeatureSource/schema/<schemaname>/<classname>.xml [or .json]
-}}}
+
+Now this is where things start to get interesting. What alternate representations do we expose for Feature Sources to support the Feature Services API? 
+
+
+''' (jb) QUESTION:  Again, I am somewhat concerned that we are introducing elements (schema, spatialcontexts, features) that the client has to just know about.  Is there any way that we can return an enumeration of these endpoints when the MyData.FeatureSource is requested?.'''
+
+We'll start with basic schema access and drill down into feature selection, update, etc. To describe the schema of a Feature Source do something like:
+
+{{{
+GET
+.../library/MyStuff/MyData.FeatureSource/schema
+}}}
+
+Want just the representation of a particular schema or even a single class? How about the following (with a type of XML or JSON):
+
+{{{
+GET
+.../library/MyStuff/MyData.FeatureSource/schema/<schemaname>
+}}}
+
+{{{
+GET
+.../library/MyStuff/MyData.FeatureSource/schema/<schemaname>/<classname>
+}}}
+
 To get a list of the Spatial Contexts the following might work:
-{{{
-GET
-.../library/MyStuff/MyData.FeatureSource/spatialcontexts.xml [or .json]
-}}}
+
+{{{
+GET
+.../library/MyStuff/MyData.FeatureSource/spatialcontexts
+}}}
+
 Retrieving all features of a given class might look something like:
-{{{
-GET
-.../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>.xml [or .json]
+
+{{{
+GET
+.../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
 
 Optional Parameters:
@@ -100 +193 @@
    orderOption=<ascending | descending>
 }}}
+
 For feature classes that have a single identity property, the following syntax may be used to retrieve a single feature:
-{{{
-GET
-.../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>/<id>.xml [or .json]
-}}}
+
+{{{
+GET
+.../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>/<id>
+}}}
+
 Where <id> is the unique id of the feature. Deleting features can be performed with the HTTP DELETE method as follows:
+
 {{{
 DELETE
 .../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>/<id>
+}}}
 
 or
 
+{{{
 DELETE
 .../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
@@ -118 +217 @@
    filter=<fdo filter>
 }}}
+
 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:
+
 {{{
 POST
 .../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
+}}}
 
 and
 
+{{{
 PUT
 .../library/MyStuff/MyData.FeatureSource/features/<schemaname>/<classname>
@@ -131 +234 @@
    filter="<fdo filter>"
 }}}
-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 I have is whether the URI should specify the expected type? 
+
+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? 
+
 [[BR]]
 [[BR]]
@@ -138 +243 @@
 [[BR]]
 [[BR]]
+
 == Alternate Representations for Maps, Map Definitions, and Layer Definitions ==
-I decided to lump the representations for Maps, Map Definitions, and Layer Definitions together as they all relate to creating and interacting with maps. The first thing that needs to be understood here is the relationship between a Map Definition (resource type !MapDefinition) and a Map (resource type Map and object representation !MgMap). These are not the same things, however they are closely related. Looking at it from a programming perspective, a Map Definition would be a class and a Map would be an instance of a Map Definition. In more human terms, a Map Definition is a template or set of rules and a map is a per client/user object built from a Map Definition template. The Map object is stored in session state and knows the current list of layers and their visibility, current scale, and current extents. Having this information server-side allows !MapGuide to render and plot maps with minimal client-server interaction. 
-[[BR]]
+
+The representations for Maps, Map Definitions, and Layer Definitions are all dealt with together as they relate to creating and interacting with maps. The first thing that needs to be understood is the relationship between a Map Definition (resource type !MapDefinition) and a Map (resource type Map and object representation !MgMap). These are not the same things, however they are closely related. Looking at it from a programming perspective, a Map Definition would be a class and a Map would be an instance of a Map Definition. In more human terms, a Map Definition is a template or set of rules and a map is a per client/user object built from a Map Definition template. The Map object is stored in session state and knows the current list of layers and their visibility, current scale, and current extents. Having this information server-side allows !MapGuide to render and plot maps with minimal client-server interaction. 
+
 The first thing we need is the ability to create a Map resource / !MgMap object.
+
 {{{
 POST
@@ -148 +256 @@
 Optional Parameters:
    name=<mapname>
-
+}}}
+
+{{{
 POST
 .../session/<uglysesssionid>/createmap
@@ -157 +267 @@
    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'''
+
+{{{
+POST
+.../session/<uglysesssionid>/MyMap.Map
+
+Required Parameters:
+  MapDefinition=http://example.org/mapguide/rest/library/MyStuff/MyMap.MapDefinition
+}}}
+
+and
+
+{{{
+POST
+.../session/<uglysesssionid>/MyMap.Map
+
+Required Parameters:
+  srs=<srswkt>
+  envelope=x1,y1,x2,y2
+}}}
+
+''' (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