Application of SuperMap iServer REST services

Introduction to REST API

SuperMap iServer provides REST-based application programming interfaces - SuperMap iServer REST APIs. These interfaces encapsulate most of the GIS functions including basic map functions, data editing functions, analysis functions, etc. SuperMap iServer provides these GIS functions to clients via SuperMap iServer REST APIs. Clients can obtain corresponding GIS functions by employing these APIs.

A SuperMap iServer REST API has the following characteristics:

Different GIS functions are encapsulated into different resources, with each resource identified by a unique URI.
A SuperMap iServer REST API implements resources, i.e., operates GIS functions, according to HTTP protocol standards. The methods include: GET (gets a resource), POST (creates a resource), PUT (creates and modifies a resource), DELETE (deletes a resource), etc.
SuperMap iServer expresses resource descriptions and GIS calculation results through resource representations. A number of output formats for representations are supported, including HTML, XML, JSON, BMP, etc.

Steps for getting a REST service

The easiness of use is one of the reasons why REST services are increasingly popular among developers. Getting a REST service can be achieved by operating on the URI of the resource. The following steps are needed to use a SuperMap iServer REST API:

1 Go over the REST service directory to determine the resource URIs, the required parameter structure, the supported output formats, etc. The user can also look up the interface information in the help document of SuperMap iServer. (This step can be skipped if the user is familiar with the resource.)

2 Build an HTTP request, including the URI of the resource, the parameters to be passed, and the HTTP method to be implemented on the resource.

Build a URI: A hierarchical structure is adopted to organize REST resources in SuperMap iServer. Every type of REST services has a root resource. For example, the root resource of map REST services is the maps resource; a child resource of maps is a map resource; and a child resource of a map is a layers resource; and so forth., The user can construct the URI of a resource according to this principle. For example, the URI of a layers resource can be:

http://192.168.1.1:8090/iserver/services/map-world/rest/maps/World Map/layers

where 192.168.1.1:8090 is a SuperMap iServer server and port;

iserver/services/map-world/rest is the root directory of the REST service, i.e., the name of the root directory.

maps/World Map is the parent resource of layers.

Parameters prepared to pass: The parameters to be passed are different for different HTTP methods and different REST resources. Therefore the user needs to determine the parameters to be passed according to the specific resource and requested method.

In SuperMap iServer, parameter information is passed in two ways when a GET request is sent: to include parameters in the URI, or to include parameters in the request body (when the volume of parameter information is large). When a POST or a PUT request is sent, parameter information is included in the request body, organized in the JSON format (default) or the XML format. The organization format of parameters in a request body is selected through setting the X-RequestEntity-ContentType information in the request header. If X-RequestEntity-ContentType is application/json, the parameters in the request body are in the JSON format; if it is application/xml, the parameters in the request body is in the XML format. The server can parse a request header and determine whether to retrieve the parameters based on the JSON format or the XML format.

Below is an example of parameters contained in a URI:

http://192.168.1.1:8090/iserver/services/map-world/rest/maps/World Map/image.bmp?center={"x":103,"y":34}&scale=0.001

Below is an example of parameters contained in a request body:

In order to change the map status of World Map (a map resource) and make its default center to be (142, 44), a PUT request can be created for the URI: http://192.168.1.1:8090/iserver/services/map-world/rest/maps/WorldMap.json, with parameters included in the request body and organized in the JSON format as follows:

{"name":"World", "center":{"x":142, "y":44}}

Note: Currently only the JSON and XML formats are supported in SuperMap iServer to organize parameters. If other formats are needed to organize parameters, the parameter decoder at the REST service end needs to be extended so that it can read parameters in the desirable format.

Determine the HTTP method implemented on the resource: Different HTTP methods have different functions. For example, a POST method is used to create a resource; a DELETE method is used to delete a resource. The client needs to determine what method is to be implemented on the resource.
Set the output format of the resource: When a request is sent to a resource, the resource will return the result to the client in an output format. The client needs to specify in what format, among the many formats supported in SuperMap iServer, the service end is going to return the representation. An output format can be set by adding .<format> to the end of the URI, e.g., http://192.168.1.1:8090/iserver/services/map-world/rest/maps.json.

3 Send an HTTP request to a REST server. A GET request can be submitted through directly entering the URI in the address bar of a browser. Other requests (POST, PUT, DELETE, and HEAD) must be submitted through programming. The implementation methods are different for different development languages.

4 Receive the resource representation from a REST. There are mainly two types of REST resources in SuperMap iServer: synchronous resources (resources that are not asynchronous are all transported synchronously) and asynchronous resources. The resource representation is returned to the client either in a synchronous fashion or in an asynchronous fashion. Therefore, when submitting an HTTP request to a REST server, a client must send a synchronous or asynchronous request according to the type of the accessed resource. Likewise, when receiving a resource representation from a REST server, a client needs to obtain the resource representation in a fashion proper for the resource type (synchronous or asynchronous). For example, a client needs to send a synchronous request on the area resource which is a synchronous resource, and obtain the representation of the area resource synchronously. Currently, most of the resources in SuperMap iServer are synchronous.

5 Parse the resource representation according to the response structure of the resource, and extract needed information. A code representing the HTTP status will be returned by the REST server in respond to the client's request. The response code tells the client the processing status of the request, such as whether or not successful, the cause of an error, etc. If the response code indicates a success, the client can go on to parse the returned resource representation. Resource representation returned in a REST service can be in one of many supported formats, such as XML, HTML, JSON, and PNG. The specific format depends on the choice of the client when sending the request. If the response code indicates an operation failure, the client can obtain the cause of the error.

Obtaining a REST service directly through a URI

Among the HTTP methods, only the GET method is supported by the browser by default. The GET method is used by clients to retrieve information description of a resource. Therefore, the directories and functions of various resources in a REST service can be obtained by directly entering the resource URI in the address bar of a browser. Additionally, adding a suffix similar to .[format] to a URI can result a returned response displayed in a certain specified format. Below are two examples of URIs entered in the address bar, followed by their interpretations respectively:

http://192.168.1.1:8090/iserver/services/components-rest/rest.html

the REST service directory will be displayed in HTML format.

http://192.168.1.1:8090/iserver/services/components-rest/rest/maps/World Map/image.png

indicates that a GET method is to be implemented on the image resource of World Map to retrieve the map image.

Obtaining a REST service through JavaScript

JavaScript is usually used to create and send a request via XMLHTTPRequest, and to respond to a server. Commonly used methods are:

open(): creates a new request to a server.
send(): sends a request to a server.
abort(): aborts the current request.
readyState: provides the ready state of the current HTML.
responseText: the returned text from the server in response to the request.

According to the developing steps described above, a URI is created first, then a request is sent, and finally the result is received and parsed. Below is an example in which the center of World Map is altered.

The resource URI: http://192.168.1.1:8090/iserver/services/map-world/rest/maps/World Map

The returned output format of the resource: JSON

The HTTP methods used: GET and PUT. The GET method is used first to retrieve the basic map information of World Map. The PUT method is then used to change the value of the center point included in the basic map information retrieved by the GET method.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<HTML>

<HEAD>

</HEAD>

function GetMapInfo() {

request = new ActiveXObject("Msxml2.XMLHTTP");

var uri="http://localhost:8090/iserver/services/maps/rest/maps/World Map.json";

request.open("GET",encodeURI(uri),false,"","");

request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded; charset=UTF-8");

request.send(null);

if(request.status==200){

//Parse the json string returned by the server into a JavaScript object. json_parse() is a method for parsing json in the json_parse.js file.

var response = json_parse(request.responseText, null);

//Gets the Div container for display.

var container = document.getElementById('container');

//The output result

container.innerHTML="";

container.innerHTML += '<p>the map name: ' + response.name +'</p>';

container.innerHTML += '<p>the displaying boundary of the map: <li>leftBottom: ' + toJSON(response.bounds.leftBottom) +'</li>'+'<li>rightTop: '+toJSON(response.bounds.rightTop)+'</p>';

container.innerHTML += '<p>the extent of the user viewing window: <li>leftTop: ' + toJSON(response.viewer.leftTop) +'</li>'+'<li>rightBottom: '+toJSON(response.viewer.rightBottom)+'</p>';

container.innerHTML += '<p>the map scale: 1: ' + Math.round(1/response.scale) +'</p>';

}else{

alert("Operation failed!");

}

</script>

<BODY>

</BODY>

</HTML>

Note: when this method is used to obtain a REST service, files json_parse.js and toJSON.js need to be copied from Installation directory/samples/code/HelloREST to the directory where HelloREST.html is. json_parse.js contains the json_parse method for parsing a JSON string to an Object object in javascript. toJSON.js contains the toJSON method for parsing an Object object to a JSON string.

Obtaining a REST service through Silverlight

SuperMap provides a development kit SuperMap iClient 6R for Silverlight for rich clients of Silverlight. This kit encapsulates a series of interfaces connecting the REST services of iServer, simplifying users' development process greatly.

Obtaining a REST service through SuperMap iClient 6R for Silverlight API is illustrated with the following example of displaying the data of World Map:

Resource Url: http://192.168.11.33:8090/iserver/services/map-world/rest/maps/World Map

The classes used	Description
Map	The map tool for loading various types of map layers
DynamicRESTLayer	A dynamic REST layer, i.e., a REST layer used as the dynamic layer of a map service

<UserControl x:Class="SampleCode.DynamicRESTLayerTest"

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

xmlns:icMapping="clr-namespace:SuperMap.Web.Mapping;assembly=SuperMap.Web"

xmlns:iclayer="clr-namespace:SuperMap.Web.Mapping;assembly=SuperMap.Web.iServerJava6R">

<icMapping:Map x:Name="MyMap">

<iclayer:DynamicRESTLayer Url="http://192.168.11.33:8090/iserver/services/map-world/rest/maps/World Map" />

</icMapping:Map>

</Grid>

</UserControl>

As shown in the above code, the user only needs to set the url properties to load a map service published by a REST when using SuperMap iClient 6R for Silverlight API. In fact, only the map name needs to be specified. iClient will automatically parse the map regardless of the format in which the map is returned. The programming process is therefore simplified greatly.