Tuesday 1 April 2014

GeoREST as re-imagined by mapguide-rest: Part 2 - The XML adapter

For this post, we are going to talk about one of the adapters provided by mapguide-rest: The XML adapter.

This won't be a comprehensive guide, you can consult the adapter documentation in the github wiki for all the gritty details. This will just be a basic overview of the adapter

The XML adapter lets you provide an XML representation of feature data from any MapGuide Feature Source. The name of this adapter is FeatureSetXml. When reading XML via this adapter (using HTTP GET), the XML is the same format as the XML data returned by a SELECTFEATURES operation from the mapagent.

While the value of consuming MapGuide feature data in this format may be debatable, what the XML adapter special and where it is most valuable is that it is the only adapter to support CRUD through the quartet of HTTP verbs:
  • GET: For reading one or more features
  • POST: For inserting one or more features
  • PUT: For updating one or more features
  • DELETE: For deleting one or more features
All other adapters only provide GET support (to "read" feature data as a particular format). This is the only adapter to support feature manipulation.

Configuration

To enable XML representation support for your feature source, your restcfg.json should look like this:

{
    "Source": {
        "Type": "MapGuide",
        "FeatureSource": "Library://Samples/Sheboygan/Data/Parcels.FeatureSource",
        "FeatureClass": "SHP_Schema:Parcels"
    },
    "Representations": {
        "xml": {
            "Adapter": "FeatureSetXml",
            "Methods": {
                "GET": {
                    "MaxCount": 500
                },
                "POST": {},
                "PUT": {},
                "DELETE": {}
            }
        }
    }
}

The above configuration will enable support for all 4 HTTP methods. If you do not want to support a particular method on this Feature Source, then simply remove the corresponding method key from the Methods section of the above configuration. Attempts to make requests to this data source using such un-configured methods will return HTTP 405 (method not allowed).

Reading XML Features

Assume the above restcfg.json resides in /conf/data/property/restcfg.json

To get the XML of this data source is simply to issue a GET request like this:

GET http://servername/mapguide/rest/data/property/.xml


The number of features in this result will be capped at 500 due to the MaxCount property in the configuration.

You can also request the XML of a single feature by putting the actual ID value of the feature into the URL like so

GET http://servername/mapguide/rest/data/property/45.xml


Inserting XML Features

Assume the above restcfg.json resides in /conf/data/property/restcfg.json

Inserting a new feature requires a HTTP POST to the multiple results URL. Your XML body should be structured as follows:

  • A top-level FeatureSet element
  • With a Features element
  • With a Feature element for each feature you want to insert.
  • Each Feature element should have one or more Property elements
  • Each Property element should have a Name element containing the property name and a Value element containing the property value. Geometry values must be in WKT format

A successful request will return an XML envelope containing the ID values for the inserted feature.



Updating XML Features

There are 2 ways to update features.

  • A PUT request to the multiple results URL
  • A PUT request to the single result URL
Your XML request body must be structured as follows
  • A top-level UpdateOperation element
  • With a Filter element which is the FDO filter for features to be updated. If issuing a PUT request to a single results URL, this element is not required as the filter can be inferred from the URL itself.
  • Also with a UpdateProperties element
  • Containing one or more Property elements
  • Each Property element should have a Name element containing the property name and a Value element containing the property value. Geometry values must be in WKT format. Null values can be specified by omitting the Value element.
Note that on IIS, PUT requests is probably not allowed by default, so you'll probably have to use a POST request and include a X-HTTP-Method-Override = PUT request header.

Sending the request will return an XML envelope indicating the number of features updated by this request.


Deleting Features

Like updating, there are 2 ways to delete features
  • A DELETE request to the multiple results URL
  • A DELETE request to the single result URL
No XML request body is required. You just have to specify a filter parameter that indicates what features will be deleted. If the request is to a single result URL, this parameter is not required as the filter will be inferred from the URL itself.

Like PUT, DELETE is probably not allowed on IIS by default, so you can work around that by using a POST request and include a X-HTTP-Method-Override = DELETE request header.

Sending the request will return an XML envelope indicating the number of features deleted by this request


Transaction Support

For providers that support it, you can configure such CRUD operations to use transactions by specifying UseTransaction: true in the relevant methods in restcfg.json

{
    ...
    "Representations": {
        "xml": {
            "Adapter": "FeatureSetXml",
            "Methods": {
                "GET": {
                    "MaxCount": 500
                },
                "POST": {
                    "UseTransaction": true
                },
                "PUT": {
                    "UseTransaction": true
}, "DELETE": {
                    "UseTransaction": true
                }
} } } }

In Summary

The XML adapter is useful for doing CRUD operations using standard HTTP requests and the specially crafted XML request envelopes as described in this post. No special code or APIs required!

3 comments:

Johan Van de Wauw said...

Just wondering: how would you manage user authentications. You probably don't want anyone to be able to update/delete features?

Jackie Ng said...

Yes that's true.

Right now Anonymous MG user can indeed do quite some damage if such stuff was hosted publicly (good thing this is right now a preview-level release and not something production-ready)

I'm guessing right now if we want simplicity and leverage the existing MG user/group system, then perhaps defining some kind of user/group ACL in the restcfg.json and 403/401 any unauthorized user/group should do the trick.

Feel free to continue this discussion on (https://github.com/jumpinjackie/mapguide-rest/issues/43). This is definitely something that has to be addressed before I can confidently say that mapguide-rest is ready for production use.

darshan ganatra said...

I am facing one problem while two user simultaneously viewing same maps from different browser at that time map will be filter automatically as per newer filter value. old filtered map is not allowing me to select any point for viewing in the panel...

I hope you understood my problem..

Please help me.... I am waiting for your reply