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!