REST API 简介

SuperMap iServer 提供了基于 REST 的应用编程接口——SuperMap iServer REST API，这些接口封装了大部分的 GIS 功能，包括基本的地图功能，数据编辑功能，分析功能等。SuperMap iServer 将这些 GIS 功能通过 SuperMap iServer REST API 提供给客户端，客户端使用这些 API，能够获取到相应的 GIS 能力。

SuperMap iServer REST API 包括以下特点：

  • 所有 GIS 能力被封装为不同的资源，并且每一个资源通过唯一的 URI 进行标识。
  • SuperMap iServer REST API 使用 HTTP 协议标准的方法实现对资源的操作，即对 GIS 功能的操作。包括：GET（获取资源）、POST（创建资源）、PUT（创建、修改资源）、DELETE （删除资源）方法等。
  • SuperMap iServer 对资源的描述以及 GIS 计算结果通过资源表述的方式表达，且支持多种格式的资源表述，包括 HTML、XML、JSON、BMP 等。

 使用 REST API 的基本流程

REST 服务越来越受到开发者的欢迎其中一个原因就是使用 REST 服务比较简单，因为获取 REST 服务基本上就是通过对资源的 URI 的操作实现的。使用 SuperMap iServer REST API 大致要分为以下几个步骤：

  1. 浏览 REST 服务目录，确定资源 URI、需要的参数结构、支持的表述格式等。

您可以通过 SuperMap iServer 的帮助文档查阅 REST API 的接口信息。（如果比较了解资源，此步骤可以省略。）

  1. 构建 HTTP 请求，包括资源的 URI 、所需传递的参数、对资源执行的 HTTP 方法。
  • 构建 URI：SuperMap iServer 的 REST 资源采用层次结构组织，每一类 REST 服务都有一个根资源，如地图 REST 服务的根资源为 maps，maps 的子资源为 map，layers 资源为 map 资源的子资源，以此类推。根据这一的规则，用户可以构建资源的 URI。如 layers 资源的 URI 为：

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

其中，192.168.1.1:8090 是 SuperMap iServer 服务器地址和端口， iserver/services/map-world/rest 是 REST 服务的根目录，即 root 目录名称。 maps/World Map 是 layers 的父资源。

  • 整理待传递的参数：REST 资源不同，执行的 HTTP 方法不同所需要传递的参数可能不同，因此用户需要针对具体的资源和请求的方法，确定传递的参数内容。

在 SuperMap iServer 中规定，发送 GET 请求时，参数信息有两种传递方式，一是参数包含在 URI 中，二是参数放在请求体中（当参数信息很大的时候）。发送 POST，PUT 请求时，参数信息放在请求体中，且请求体中的参数信息以 JSON（默认方式） 或者 XML 方式组织。请求体中的参数组织格式的选择通过设置请求头中的 X-RequestEntity-ContentType 信息来决定。 X-RequestEntity-ContentType 为 application/json 时，标识请求体中的参数为 JSON 格式，为 application/xml 时，标识请求体中的参数为 XML 格式。服务器通过解析请求头，就能知道该按照 JSON 还是 XML 的格式来解析参数。

例如：参数包含在 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

参数包含在请求体中：

对地图 World Map（map 资源）进行地图状态修改，使其默认中心点改为（142，44），可以对 URI：http://192.168.1.1:8090/iserver/services/map-world/rest/maps/World Map.json 构建 PUT 请求，参数放在 PUT 请求的请求体里，JSON 组织形式如下：

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

说明：目前 SuperMap iServer 仅支持 JSON 和 XML 两种参数组织格式，如果需要使用其他格式组织参数，需要在 REST 服务端扩展参数解析器，使参数解析器能够解读该格式的参数。

  • 确定对资源执行的 HTTP 方法：不同的 HTTP 方法可以对资源执行不同能力的操作，如 POST 方法表示创建一个资源，DELETE 方法表示删除一个资源。客户端需要确定对资源做何种操作。
  • 设置资源表述格式：向资源发送请求，资源会将结果以资源表述的方式返回给客户端，SuperMap iServer 支持多种表述格式，因此客户端在提交请求的时候需要指定服务端返回哪种格式的表述。设置表述的格式只需要在 URI 后面加上.<format>即可，如 http://192.168.1.1:8090/iserver/services/map-world/rest/maps.json。
  1. 向 REST 服务器发送 HTTP 请求。

对于 GET 方法提交请求可以直接在浏览器的地址栏中输入 URI 即可。其他方法（POST、PUT、DELETE、HEAD）提交请求需要通过编程实现，不同的开发语言实现的方法不同。

  1. 接收 REST 返回的资源表述。

SuperMap iServer 的 REST 资源有几种类型，其中包括同步资源（除异步资源外所有资源均为同步传输机制的资源）和异步资源，即对资源的表述以同步或者异步的方式返回客户端。因此客户端在向 REST 服务器发送 HTTP 请求时，需要根据访问的资源的类型发送同步/异步请求。同理，客户端在接收 REST 返回的资源表述时，也需要根据资源的类型（同步资源或者异步资源）以正确的方式获取资源表述。如，客户端应该向 area 资源（同步资源）发送同步传输请求，并以同步传输方式获取 area 资源表述。目前 SuperMap iServer 大部分都是同步资源。

  1. 参照资源的响应结构，解析资源表述，提取所需的信息。

REST 服务器会返回 HTTP 状态代码以响应客户端请求，通过响应码，客户端可以得知请求的处理情况。例如：是否成功、出错的原因，等等。如果返回成功的响应码，客户端可以进一步解析返回的资源表述，REST 服务器响应的资源表述结果支持多种格式，如 XML，HTML，JSON，PNG 等，主要取决于客户端发送请求时对返回的资源表述的格式的选择。如果返回操作失败的响应码，客户端可以获取出错原因。

直接通过网址获取 REST 服务

在 HTTP 的方法中仅有 GET 方法是浏览器默认支持的 HTTP 方法，通过 GET 方法客户端可以获取资源的信息描述，因此，如果希望了解 REST 服务中提供的各种资源目录，各种资源的能力等，可以直接在浏览器的地址栏中输入资源 URI。如果希望返回的响应结果以某种固定的格式显示，可以给 URI 加上后缀，形如.[format]。例如在地址栏输入：

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

可以看到以 HTML 格式描述的 REST 服务目录。

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

表明向 world Map 地图的 image 资源执行 GET 方法，获取 world Map 地图图片。

通过 iClient for JavaScript 获取 REST 服务

通常 JavaScript 通过 XMLHTTPRequest 建立和发送请求，并响应服务器。经常用到的方法如下：

  • open()：建立到服务器的新请求。
  • send()：向服务器发送请求。
  • abort()：退出当前请求。
  • readyState：提供当前 HTML 的就绪状态。
  • responseText：服务器返回的请求响应文本。

根据前面介绍的开发步骤，依次构建 URI，发送请求，接收和解析结果。下面的例子是修改地图-World Map 的中心点。

资源 URI： http://192.168.1.1:8090/iserver/services/map-world/rest/maps/世界地图

返回的资源表述格式：JSON

使用的 HTTP 方法：GET 和 PUT。先使用 GET 方法获取 World 的基本地图信息。再通过 PUT 方法，修改 GET 方法获取的基本地图信息中的中心点的值。

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

<HTML>

    <HEAD>

        <TITLE>REST</TITLE>       

    </HEAD>

<script  type="text/javascript" src="json_parse.js"></script>

<script  type="text/javascript" src="toJSON.js"></script>

<script  type="text/javascript">

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

//解析从服务器端返回的 json 字符串，解析为一个 JavaScript 对象。json_parse()为 json_parse.js 文件中的一个解析 json 的函数。

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

//获取用作显示的 Div 容器。

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

//输出结果

container.innerHTML="";

    container.innerHTML += '<p>地图名：' + response.name +'</p>';

    container.innerHTML += '<p>地图显示区域：<li>leftBottom：' + toJSON(response.bounds.leftBottom) +'</li>'+'<li>rightTop：'+toJSON(response.bounds.rightTop)+'</p>';

    container.innerHTML += '<p>用户视窗范围：<li>leftTop：' + toJSON(response.viewer.leftTop) +'</li>'+'<li>rightBottom：'+toJSON(response.viewer.rightBottom)+'</p>';

    container.innerHTML += '<p>地图比例尺：1：' + Math.round(1/response.scale) +'</p>';

}else{

alert("操作失败！");

}

}  

  </script>

    <BODY>

        <input type="button"  value="GetMapInfo" onclick="GetMapInfo()" /></input>

        <br><br>

        <div align=left id="container" style="left:50px;top:50px">

    </BODY>

</HTML>

注意：通过这种方式获取 REST 服务时，需要从安装目录下，samples/code/HelloREST 目录中复制 json_parse.js 和 toJSON.js 文件到 HelloREST.html 的同级目录。json_parse.js 中包含了 json_parse 方法，用于解析 JSON 字符串为 javascript 中的 Object 对象，toJSON.js 中包含了 toJSON 方法，用于将 Object 对象转化为 JSON 字符串。