Data configuration

The data configurations are stored in each restcfg.json file in the conf/data folder or subfolders within.

restcfg.json

A restcfg.json document has two root properties:

• A Source property that defines the MapGuide Feature Source that will be enabled for REST-ful access.
• A Representation property that defines one or more representations that the configured Feature Source will be made available for. Each representation defines the name of the adapter that will handle incoming requests for that particular representation along with method-specific options for that particular adapter

Source

The Source property looks like the following:

{
    "Source": {
        "Type": "MapGuide",
        "FeatureSource": "Library://Samples/Sheboygan/Data/Parcels.FeatureSource",
        "FeatureClass": "SHP_Schema:Parcels"
    }
}

The Type property must be set to "MapGuide"

The FeatureSource property must be set to the resource ID of the Feature Source that you want to enable REST-ful access to.

The FeatureClass property must be set to the specific Feature Class within the feature source that you want to enable REST-ful access to. For performance, you should use a qualified class name as an unqualified class name will incur an additional schema name walk to get a suitable schema name.

Representation

The Representation property defines one or more accessible representations for your configured Feature Source, keyed on the extension of the representation. Each representation must specify the name of the adapter (via the Adapter property) that will handle requests for this particular representation, along with a Methods property that defines which HTTP methods are enabled for this particular representation.

Each representation has options that can be applied for that particular adapter.

An example representation configuration is shown below.

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

The xml representation is handled by the FeatureSetXml adapter. It is configured to accept GET, POST, PUT and DELETE requests. For GET requests, the MaxCount property instructs the adapter to limit the XML response to 500 features maximum. Any HTTP method that is not specified under the Methods property will be rejected by the REST extension should a client make such requests.

Folder structure to URI mapping

mapguide-rest uses the relative location of your restcfg.json files as a means of accessing that particular data source in a REST-ful manner.

Any url under http://localhost/mapguide/rest/data is considered a data URL and whatever follows it will be used to locate the matching restcfg.json and process the matching representation.

Consider the following folder structure. Assume all these configuration files have an XML representation configured with GET method access.

conf
    data
        infrastructure
            water
                restcfg.json  
            sewer
                restcfg.json
        property
            restcfg.json

Assuming the REST extension is accessible from http://localhost/mapguide/rest

To access the "water" data source as XML, the URL is: http://localhost/mapguide/rest/data/**infrastructure/water**/.xml

To access the "sewer" data source as XML, the URL is: http://localhost/mapguide/rest/data/**infrastructure/sewer**/.xml

To access the "property" data source as XML, the URL is: http://localhost/mapguide/rest/data/**property**/.xml

Please note that for security purposes, mapguide-rest will automatically strip off any parent walking parts (..) from the URI part (to prevent any malicious attempts to walk outside of mapguide-rest's designated data directory). Take note of this behavior if you are generating links to such URLs.

Filtering

By default, the regular extension (eg. /.xml) returns all features from the feature source. You can apply a MaxCount setting in the adapter configuration to apply a maximum limit on the number of features that can be returned, but you can apply additional filtering using a filter request parameter. The parameter is an encoded FDO filter string.

For example, the following URL:

http://localhost/mapguide/rest/data/infrastructure/property/.xml?filter=RNAME LIKE %27SCHMITT%25%27

Will return all features whose owner (RNAME) begins with "SCHMITT"

RNAME LIKE %27SCHMITT%25%27 is the URL-encoded form of RNAME LIKE 'SCHMITT%'

NOTE: For the security-conscious, note that the string above is not a SQL WHERE clause, but a FDO filter string. Filter strings are parsed into an FDO filter expression syntax tree before it is ever translated into SQL in the underlying SQL-capable FDO providers. Attempts to inject any form of SQL into the FDO filter will result in either an exception during the FDO filter parsing step or an inert FDO filter.

Individual feature access

All available adapters support individual feature access by providing the ID value as the "filename" of the representation in the URL.

For example, the following URL:

http://localhost/mapguide/rest/data/infrastructure/property/45.xml

Returns the XML of the property feature whose Autogenerated_SDF_ID value (the identity property of this feature class) is 45

NOTE: Individual feature access will not work for feature classes that have zero or more than one identity property. Attempts to use such a URL on such a configured data source will throw an exception. Such feature classes are generally uncommon. But if you do encounter such a feature class, there is is a way to make individual feature access work for such feature classes.

For individual feature access to work with Feature Classes that do not satisfy the one identity property requirement (eg. An un-configured SQL Server view), you have to specify an IdentityProperty property in the Source property of your restcfg.json

{
    "Source": {
        "Type": "MapGuide",
        "FeatureSource": "Library://Data/DB.FeatureSource",
        "FeatureClass": "dbo:VW_Parcels",
        "IdentityProperty": "ParcelID"
    }
}

Individual feature access for this configured data source will use the specified IdentityProperty for constructing its individual feature FDO filter, instead of the default identity property (which wouldn't exist for such a Feature Class).

Available Adapters

mapguide-rest currently provides the following adapters

• FeatureSetXml provides XML representations of features in your configured Feature Source
  • Supported methods: GET, POST, PUT and DELETE
• FeatureSetGeoJson provides a GeoJSON representation of features in your configured Feature Source
  • Supported methods: GET
• FeatureSetCsv: provides a Comma-Separated Values (CSV) representation of features in your configured Feature Source.
  • Supported methods: GET
• MapImage provides a image-based representation of features in your configured Feature Source
  • Supported methods: GET
• Template provides a template-driven representation of features in your configured Feature Source. Templates use the Smarty template engine
  • Supported methods: GET

See Adapter Documentation for information about adapter-specific configuration options.