Tuesday, 4 February 2014

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)


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:
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:
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 :)


Reno Sun said...

Hello Jackie,

I am going to test how mapguide-rest can help our municipal GIS/AMS (Asset Management) systems. I copied the content of mmapguide-rest-master folder, and pasted them into following folder "C:\Program Files\Autodesk\Autodesk Infrastructure Web Server Extension 2014\www\rest".

However, I tested following url "http://maps.qualicumbeach.com/mapserver2014/rest/"... and it did not work.

I am using AIMS 2014 with IIS7, and the OS is windows server 2008 R2. Please let me know what did I missed. By the way, I also installed ARR that you mentioned under Setup section on the GitHub.


Jackie Ng said...

Did you rename web.config.iis to web.config after installing ARR? If not, the URL re-writing doesn't work

David said...

Hello Jackie,
nice work. I'm very excited about this new feature. I wich all geospatial coders and managers at Autodesk has same enthusiasm and productivity as you.

But enough praise, I also have a few questions:
1) Is there any way to turn on and off layers (groups) when rendering maps?
2) When I try to request resource which has non-ASCI characters in name, I always get HTTP 500. For example .../ZákladníMapa.Map Definition/Image.png?...

I'm using AIMS 2013, PHP 5.3, IIS, Win7-x64


Jackie Ng said...

1). Pass showlayers/hidelayers/showgroups/hidegroups along with your image request. These parameters take a comma-separated list of MgLayer/MgLayerGroup object ids.

2) You've exposed a problem with the underlying framework's inability to handle routes with unicode characters (I'm using Slim Framework btw). I may have to switch to an alternate PHP micro-framework that supports unicode routes if I can't find a solution for this.

Jackie Ng said...

Just an update. The Unicode URL problem only affects IIS. Unicode URLs work fine in Apache.

Not that it really helps your particular issue at the moment if you're stuck with IIS.

Canuckoid said...

Hi Jackie,
whenever accesses the data:

I get a log-on screen and none of the Administrator or Anonymous users allow me to access the data, but the:


does not prompt for the log-on and views normally..

Is there an install in IIS I am missing to avoid the log-on for the mapguide data?

Jackie Ng said...

This is your web browser caching the basic http authentication credentials for performance reasons.

I do not know whether you're using the 0.6 release or a specific git revision, but accessing a published data source in 0.6 or older git revisions should auto-create a MG Anonymous login. You should not get a HTTP authentication prompt.

On git master, the access behavior is controlled by ACL settings in restcfg.json (see: https://github.com/jumpinjackie/mapguide-rest/issues/43)

Jackie Ng said...

@David, the 0.7 release should fix the HTTP 500 errors on unicode URLs

RenoSun said...

Hey Jackie I renamed web.config.iis to web.config after installing ARR. However, it showed me following message "The page cannot be displayed because an internal server error has occurred." I tried both "http://maps.qualicumbeach.com/mapserver2014/rest/index.php/library/list.html" and "http://maps.qualicumbeach.com/mapserver2014/rest/library/list.html" but get the same error message.

Please let me know if I did miss something...thanks!

PTI said...

I have a question, whenever we try to update a feature it always prompts for Authentication within Fusion. The login failed the first time and than just continually says failed to update with a 403 error (Permission denied). How do I address this? I would like the layer to be open to editing with a prompt..

Jackie Ng said...


Updating features via /library/... route?

You have to set a resource header value _MgRestAllowUpdate to 1 in the Feature Source to allow updates, otherwise updates to that feature source via this API are forbidden (403)

Update via a data source under /data/... ?

You must make sure in your restcfg.json that your MG user or group is allowed to send PUT requests

Unknown said...

My name is irfan, I'm doing research about using cesium js using mapguide. So far I have found installation manual mapguide-rest install, if you want, please tell me more advance about how to install mapguide-rest and connect it with cesium js

Sorry I am not fluent in english