Introducing mapguide-rest: A new REST extension for MapGuide

Over the New Year, I've been thinking about how we can give MapGuide a proper REST API.

While mapguide4j was a nice experiment which explored this very idea, being written in Java ultimately was too much of a technological burden for me and for the user. The installation story is just horrible for users.

• Install a JDK
• Extract the mapguide4j zip to your install directory
• Copy MapGuide dlls and jars (assuming you installed MapGuide with Java options enabled) into the mapguide4j directory
• Start up the play framework and hope "Jarmageddon" doesn't ensue

While Java wasn't necessarily a bad choice, it was just too enterprise-y to offer a pleasant developer experience for me and installation experience for potential users. As a result, I've aborted that project and it is now relegated to being a big piece of sample code for anyone wondering how a MapGuide application could be built in Java.

At the same time, I also wanted to integrate features from GeoREST to provide a one-stop-shop REST API for MapGuide. Adding it to mapguide4j was not going to happen for reasons already stated.

So I went back to the drawing board, and the project known as mapguide-rest was born. So here's a little introduction.

mapguide-rest is a REST extension for MapGuide Open Source that is the amalgamation of ideas and features explored and implemented in the mapguide4j and GeoREST projects. It is written in PHP and works on both Windows and Linux versions of MapGuide. It provides the following services:

• A REST API modeled on original discussions of a RESTful web service for MapGuide, and builds on top of what was already implemented and provided by mapguide4j.
• A RESTful spatial data publishing framework similar to GeoREST. If you have used GeoREST before, this should be very similar to you.

In addition, it should also theoretically work on any release of MapGuide/AIMS (Windows or Linux) that bundles PHP 5.3 or newer, without having to muck around with any binaries, dlls or external dependencies although some bugs in earlier versions of MapGuide/AIMS may break or alter behaviour in some parts of the REST API.

For reliability, we recommend that you use mapguide-rest with the latest stable release of MapGuide (2.5.2). This is the version of MapGuide I have been building and testing on.

Installation of mapguide-rest is also a simple process (see Installation section below)

Motivation

As mentioned, I wanted something similar to what I already had with mapguide4j, but not Java.

At the same time, I was primarily disappointed by the glacial (dead?) pace of GeoREST development. While GeoREST is bundled with every yearly release of AIMS, the most recent binary release on the Google Code site was 3 years ago.

Despite being open source, the codebase and build system/process for GeoREST just wasn't conductive to external contribution. For the longest time, I tried to get this thing to build in 64-bit and for recent releases of MapGuide Open Source, but with no instructions on how to build key 64-bit dependencies required by GeoREST (Google also failed me here), I just gave up and moved on to other productive activities. If you're using MapGuide Open Source, especially recent stable releases (like me), you're out of luck trying to get GeoREST working on such a release.

If we want the publishing capabilities of GeoREST with the RESTful API explored by mapguide4j, and do this in a language more developer-friendly and productive than C++, whose application is easy to install for the end user and has the necessary bindings to the MapGuide API then the logical conclusion of what to build mapguide-rest on top of was simple: Build it with PHP.

I know PHP might have a bad rap in some developer community circles and some might snicker at my choice to build mapguide-rest in this language, but in the context of MapGuide applications, PHP was the most logical choice for the following reasons:

• It works on both Windows and Linux installations of MapGuide. Truly write once, run anywhere. I wasn't going to build yet another windows-only MapGuide web extension
• PHP is always installed with MapGuide, regardless of your installation choice. It is after all, required by Fusion, the Site Administrator and other assorted web applications that are part of the MapGuide Web Tier. So whatever we build can be trusted to "just work" out of the box.
• As a result of the above, the PHP binding to the MapGuide API is probably also the most "battle-hardened" of the 3 bindings we provide to the MapGuide API. If there were any stability or memory leak problems with the PHP binding, they would've been exposed by the many years of production use by Fusion, AJAX viewer and related PHP MapGuide applications and fixed appropriately.
• Installation of PHP web applications is simple. Drop its directory into the www directory of your MapGuide installation and away you go. Web-server configuration can be handled via web.config or .htaccess files. No need to muck with IIS manager (for ASP.net) or editing Tomcat configuration files (for Java).

Installing mapguide-rest

UPDATE: For greater simplicity, just grab one of the release zip files.

Here's how you can install mapguide-rest.

Firstly, go to the project page on GitHub. 

Then grab a zip of the latest revision on master

Extract this zip archive to your www directory of your MapGuide installation. On windows, this is normally C:\Program Files\OSGeo\MapGuide\Web\www. On linux, this is /usr/local/mapguideopensource-x.y.z/webserverextensions/www where x.y.z is your version of MapGuide.

Rename this mapguide-rest-master directory to rest

If you're on Linux, you'll need to do the following:

• Create a templates_c directory under rest and make sure it has sufficient permissions and ownership so the Smarty Template Engine can store compiled templates. See this link for more information.
• Make sure a default timezone has been set in php.ini

If you're on IIS7 or above, install and enable the latest version of the Application Request Routing module for IIS. Once you have done this, you can then rename the web.config.iis file within to web.config to activate URL rewriting for the rest directory. On Linux, a .htaccess file is included that will activate mod_rewrite for that directory.

Once you have done the above steps, you can now start exploring everything that mapguide-rest has to offer:

• Browse the site repository and explore all the resources and various representations: http://localhost/mapguide/rest/library/list.html
• Browse the coordinate system catalog: http://localhost/mapguide/rest/coordsys/categories.html
• Browse the FDO provider registry: http://localhost/mapguide/rest/providers.html
• Have a look at the Sheboygan Parcels set up through the GeoREST-style publishing framework: http://localhost/mapguide/rest/data/property/.html

If you are unable to set up URL rewriting, it just means you'll have an index.php in the above URLs, which will now look like this:

• http://localhost/mapguide/rest/index.php/library/list.html
• http://localhost/mapguide/rest/index.php/coordsys/categories.html
• http://localhost/mapguide/rest/index.php/providers.html
• http://localhost/mapguide/rest/index.php/data/property/.html

Want more information? 

• Check out the (ever-evolving) wiki.
• Ask a question on the mapguide-users mailing list.
• Stay tuned to this blog as I will detail some of the cool stuff that can be done :)