SuperMap iServer 的 REST 服务内容较为丰富，每一类服务内容又包含多个资源分别实现相应的 GIS 功能，用户可以通过 URI 直接在浏览器中浏览 REST 服务目录、服务内容与支持的操作和表述类型，从而快速了解发布的 REST 服务内容，以便获取适合自身系统需求的资源服务。

获取 REST 服务目录

SuperMap iServer 将 REST 服务的各种资源按照一定的层次结构组织和发布，如图 1所示，用户可以通过 REST 服务的根资源获取 REST 服务的目录，从而快速查找定位到所需的资源。

图 1 资源层次结构示意图

如上图所示 root 资源是所有 REST 服务的根资源，SuperMap iServer 提供的地图 REST 服务、数据 REST 服务、空间分析 REST 服务以及三维 REST 服务都作为 root 资源的子资源。root 资源支持 GET、HEAD 操作，通过对 root 资源的 GET 操作，可以获取所有发布的 REST 服务的目录，HEAD 请求可以用来判断 root 资源是否存在，或者客户端是否有权限访问 root 资源。通过对加.<format>的 URI 执行 HEAD 请求，还可以快速判断 root 资源是否支持<format>格式的表述。

打开 web 浏览器，在地址栏中输入 root 资源的 URI（实际上是对 root 资源执行 GET 操作），格式如下：

http://<server>:<port>/iserver/services/{component}/rest[.<format>]

例如：在地址栏输入 http://192.168.1.1:8090/iserver/services/components-rest/rest.html，可以看到以 HTML 格式描述的 REST 服务目录。

获取 REST 服务详细信息

在使用 REST 服务之前了解 REST 服务所支持的服务内容即所服务的地图，REST 服务的资源内容，REST 服务的资源支持的操作，才能有的放矢地获取所需要的 REST 服务。

上文介绍通过对根资源 root 的 GET 操作获取 REST 服务目录，也可以直接在 web 浏览器中输入 REST 服务的地址获取服务目录页面。SuperMap iServer 对服务目录页面（即 HTML 的表述）做了一定的处理，用户在服务目录页面点击每一个 REST 服务的超链接可以直接浏览该类服务的详细信息，如服务的地图名称，服务的能力（即资源列表）等。依次类推，如果是目录资源，那么目录资源的描述页面会列出子资源目录，点击每一个子资源，可以浏览子资源的描述页面。总的来说，用户通过 web 浏览器对 root 资源的访问可以获取发布的所有 REST 服务以及资源的信息。

以地图 REST 服务信息获取为例，说明 REST 服务信息的获取。

在 web 浏览器中输入 REST 服务地址，如 http://192.168.1.1:8090/iserver/services/components-rest/rest，出现 REST 服务目录，点击 maps 资源，进入地图 REST 服务描述页面即 maps 资源描述页面。如图2所示，该页面列出了 maps 资源的子资源，同时显示 maps 资源支持的 http 方法和表述格式，点击表述格式的超链接，会下载该类表述文件，如点击 xml，会下载 xml 的 maps 资源的 GET 表述。

图2 maps 资源

点击 World Map 地图，可以看到对 World Map 地图服务的 map 资源的表述，这里描述了 World Map 地图范围，默认中心点、比例尺等信息，还列出了为 World Map 地图服务的各种算法资源、静态资源等子资源列表。

点击某一 map 的子资源，如 image 资源，可以浏览到当前 image 资源的 GET 操作的表述，甚至该页面对 GET 操作需要输入的参数给出了交互式的设计，用户在 web 页面的输入框中输入参数数值，点击“获取图片” 按钮，就可以获取对应的结果。

SuperMap iServer 将 REST 资源的 HTML 表述进行了深度加工，使得用户通过浏览器就可以快速的查阅发布的 REST 服务的目录，各种算法资源的计算信息、相关参数，甚至是直接在 web 浏览器中进行交互式的 REST 资源操作。

操作 REST 资源

SuperMap iServer 发布的 REST 服务是一个真正意义的 restful 的 web 服务，任何对资源的操作行为都是通过 HTTP 协议来实现，获取资源的表述用 GET 方法，修改资源用 PUT，添加资源用 POST 或者 PUT，删除资源用 DELETE。REST 资源还支持 HEAD 操作，它只返回消息头，不返回表述，用于得到资源的元数据，比如是否可访问，是否支持某种表述格式等。

  • GET 操作：获取资源表述。

SuperMap iServer 的所有 REST 资源都支持 GET 操作，通过 GET 动作可以获取资源的表述，包括资源支持的 HTTP 动作、支持的表述类型。对目录型资源（如各类 REST 服务的第一级资源）执行 GET 操作可以获取子资源的列表。算法资源的 GET 操作通常可以获取算法的结果，如对 image 资源执行 GET 操作，能够获取地图图片。

对资源做 GET 操作可以直接通过 web 浏览器执行，因为默认情况下，浏览器向 web 服务器发送的都是 GET 方法的请求。如，在 web 浏览器地址栏中输入：http://192.168.1.1:8090/iserver/services/components-rest/rest/maps/World Map/image.png ，表明向 World Map 地图的 image 资源执行 GET 方法，获取 World Map 地图图片。

开发者也可以通过各种开发语言（如 JavaScript）向 REST 资源作 GET 操作。

  • PUT 操作：修改/添加资源。

PUT 方法既可以用来修改资源也可以用来添加资源。如果应用系统希望向 REST 资源请求 PUT 操作，通常需要通过开发语言实现，不能够简单在 web 浏览器的地址栏中输入 URI。PUT 请求体中必须包含一些参数，如果参数合法，SuperMap iServer 服务器会根据这些参数，创建或修改资源，并返回客户端操作是否成功的响应码。例如，用 JavaScript 语言向 map 资源执行 PUT 操作，以便实现修改 World Map 地图的中心点。

method="PUT";

    //data 是参数内容。

    uri="http://supermapiserver:8090/iserver/services/components-rest/rest/maps/World Map.json";

    data="{\"name\":\"World Map\", \"center\":{\"x\":142, \"y\":44}}";

    xmlhttp.open (method, url, false);

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

    xmlhttp.setRequestHeader ("Content-Length", data.length);

    xmlhttp.send (data);

 

  • POST 操作：添加资源。

对资源执行 POST 动作表示添加一个资源，与 PUT 方法不同的是，POST 添加资源是向一个已存在的 URI 发送请求，而 PUT 方法是向一个不存在的 URI 发送请求。例如，向 layers 资源（图层集合）请求添加一个图层，由于 layers 资源的 URI 是一个已存在的 URI，因此应该通过 POST 方法执行该操作。如果想对 layer 资源执行添加一个图层的操作，则需要通过 PUT 方法执行。

与 PUT 方法一样，如果应用系统希望向 REST 资源请求 POST 操作，通常需要通过开发语言实现，而且请求的参数需要包含在 POST 请求体中。

  • DELETE 操作：删除资源。

对资源执行 DELETE 操作表示删除该资源。同样，如果应用系统希望向 REST 资源请求 DELETE 操作，通常需要通过开发语言实现。

  • HEAD 操作：获取资源元数据。

执行 HEAD 操作会返回跟 GET 请求一样的 HTTP 响应头，但是没有响应实体。可以在不必传输整个响应内容的情况下，获取包含在响应消息头中的元数据信息。元数据信息包括媒体类型，字符编码，压缩编码，实体内容长度等。

HEAD 请求可以用来判断资源是否存在，或者客户端是否有权限访问该资源。通过对加.<format>的 URI 执行 HEAD 请求，还可以快速判断该资源是否支持<format>格式的表述。

资源响应码

客户端向 SuperMap iServer 服务器发送 HTTP 请求时，SuperMap iServer 服务器会根据请求的类型返回响应结果，通过响应结果中的响应码，客户端可以得知请求的处理情况。例如：是否成功、出错的原因，等等。

HTTP 协议定义了各个响应码代表的意义，官方定义有41种响应码，SuperMap iServer 主要用到其中的2xx 系列、4xx 系列和5xx 系列，各个响应码的含义如下表所示：

响应码值

 含义
200

表示服务器成功执行了客户端的 HTTP 请求。

如果请求的类型是 GET 说明获取资源成功，是 PUT 说明修改资源成功，是 DELETE 说明删除资源成功，是 HEAD 说明获取资源的元数据成功。
201

表示服务器按客户端的请求成功创建了一个新资源。对应的请求类型是 POST 或 PUT。

注意，这时返回的信息中会包含 Location 报头，指向新创建资源的规范 URI。
400

表示客户端的请求参数不合法或没有表达足够的信息。

例如，对 layers 资源执行 POST 操作创建一个新的图层，即 layer 资源，但如果没有在请求体里给出创建新图层必须的参数，即图层的描述信息，这时就会得到响应码400。
401

表示因为安全的原因，导致对资源的操作没有完成。

例如，创建一个新的图层，可以对 layers 资源执行 POST 请求（包含参数），URI 如下：

http://<server>:<port>/iserver/services/{component}/rest/maps/World Map/layers.json

而创建新图层需要管理员权限，假设某个客户端没有这个权限，当它执行以上请求时，就会得到响应码401。
404

表示客户端请求的资源不存在，即 URI 无效。

例如，在获取名为 World Map 的 map 资源时，对如下 URI 执行 GET 请求：

http://<server>:<port>/iserver/services/{component}/rest/maps/World Map.json

正常返回响应码200，说明成功获取资源；但当服务器（server）里根本没有名为 World Map 的 map 资源时，就会返回响应码404，表示资源无效。
405

表明资源不支持该操作。

例如：对 maps 资源执行 PUT 和 DELETE 请求会得到响应码405，表示 maps 资源对 PUT 和 DELETE 不支持。
406

表示资源不支持客户端请求的表述格式（参见 SuperMap iServer REST API 输出格式介绍）。

例如，在获取 maps 资源时，对如下 URI 执行 GET 请求：

http://<server>:<port>/iserver/services/{component}/rest/maps.bmp

因为 maps 不是图片资源，所以不支持 BMP 的表述格式，这时就会得到响应码406。
500 表示服务器端发生非预期情况，导致请求没有完成。

 

输出格式

REST 服务对客户端 HTTP 请求做出响应通常以各种格式的表述返回给客户端。如果客户端执行 GET 请求，资源将返回对该资源的表述；如果客户端执行 PUT、POST、DELETE 请求，资源将返回操作结果的表述。REST 资源支持的表述有多种格式，如 HTML，XML，JSON，RJSON，PNG，BMP，GIF，JPG 或者 JPEG 等，其中 PNG，BMP，GIF，JPG 或者 JPEG 是图片资源特有的表述格式。

表述的格式在 HTTP 请求的 URI 中指定，形式是在 URI 后面加上.<format>。例如对 http://<server>:<port>/iserver/services/{component}/rest/maps.json 执行 GET 请求，就会返回 json 格式的 maps 资源的表述。如果不指定<format>，资源以默认的表述格式返回相应表述。对于 GET 请求，默认返回 html 格式的表述；而对于 PUT、POST 和 DELETE 请求，默认返回 rjson 格式的表述。

对于图片资源的表述类型，通常资源会返回客户端要求的图片格式，如 png 等。但是如果资源在处理过程中出现错误，无法正确出图，出错信息将以 json 格式返回。说明：如果 REST 服务以 Debug 模式运行（在 AppContext.xml 中 REST 配置项的 debug 字段为 true），出错信息将以 HTML 格式返回。

以下是 REST 资源常见的几种表述格式。

  • HTML 格式的表述

默认的非图片资源表述格式。返回一个 HTML 页面。HTML 可以容易地表达一个列表，而且可以用标准属性（class）表达列表的种类。

例如，要获得 maps 服务的 HTML 表述，可以用以下 URI：

http://<server>:<port>/iserver/services/{component}/rest /maps.html

因为 html 是默认的非图片资源表述格式，所以也可以不指定，直接使用如下 URI：

http://<server>:<port>/iserver/services/{component}/rest/maps

输入 URI：http://localhost:8090/iserver/services/maps/rest/maps.html，

返回的表述如图3所示：

图 3 HTML 表述

  • XML 格式的表述

返回一个 xml 格式的文档。SuperMap iServer 自定义了一系列 XML 词汇，以便更准确地表述资源。

例如，要获得 maps 服务的 XML 表述，可以用以下 URI：

http://<server>:<port>/iserver/services/{component}/rest/maps.xml

返回的示例如下所示：

<?xml version="1.0" encoding="UTF-8"?><list>

  <ChildResource>

    <name>World Map</name>

    <resourceType>StaticResource</resourceType>

    <path>http://localhost:8090/iserver/services/components-rest/rest/maps/World Map.xml</path>

    <supportedMediaTypes>

      <string>application/xml</string>

      <string>text/xml</string>

      <string>application/json</string>

      <string>application/rjson</string>

      <string>text/html</string>

    </supportedMediaTypes>

  </ChildResource>

</list>

  • JSON 格式的表述

返回一个 JSON 字符串。JSON（JavaScript Object Notation）是一种 JavaScript 对象表示法，是一种轻量级的数据交换格式，可以表达一般的数据结构。

例如，要获得 maps 资源的 JSON 表述，可以用以下 URI：

http://<server>:<port>/iserver/services/{component}/rest/maps.json

返回的示例如下所示：

[{"resourceConfigID":null, "name":"World", "path":"http://localhost:8090/iserver/services/components-rest/rest/maps/World Map.json", "supportedMediaTypes":["application/xml", "text/xml", "application/json", "application/rjson", "text/html"], "resourceType":"StaticResource"}]

  • RJSON 格式的表述

执行 PUT、POST、DELETE、HEAD 请求时默认的操作结果表述格式。返回一个格式化了的 JSON 字符串，更便于阅读。

例如，要获得 maps 服务的 RJSON 表述，可以用以下 URI：

http://<server>:<port>/iserver/services/{component}/rest/maps.rjson

返回的示例如下所示：

[{

    "name": "World Map",

    "path": "http://localhost:8090/iserver/services/components-rest/rest/maps/World Map.rjson",

    "resourceConfigID": null,

    "resourceType": "StaticResource",

    "supportedMediaTypes": [

        "application/xml",

        "text/xml",

        "application/json",

        "application/rjson",

        "text/html"

    ]

}]

  • jsonp

JSONP（JSON with Padding）是 JSON 格式的一种补充，用于方便客户端实现跨域访问。

例如，要获得 maps 资源的 JSONP 表述，指定回调函数名为 mycallbackname，可以用以下 URI：

http://supermapiserver:8090/iserver/services/components-rest/rest/maps.jsonp?callback=mycallbackname

返回的示例如下所示：

mycallbackname([{

    "resourceConfigID": null,

     "name": "World",

     "path": "http://supermapiserver:8090/iserver/services/components-rest/rest/maps/World",

     "supportedMediaTypes": ["application/xml", "text/xml", "application/json", "application/rjson", "text/html", "application/jsonp", "application/ajax",      "application/silverlight"],

     "resourceType": "StaticResource"

}])

 

  • PNG 格式的表述

返回请求的 PNG 格式图片，仅当资源是图片时有效。 例如，要获得名为 World Map 的地图的当前显示，格式为 PNG，可以用以下 URI： http://<server>:<port>/ iserver/services/{component}/rest/maps/World Map/image.png 返回结果为 png 格式的图，如图 4：

图 4 PNG 表述

  • BMP 格式的表述

返回请求的 BMP 格式图片，仅当资源是图片时有效。

例如，要获得名为 World Map 的地图的当前显示，格式为 BMP，可以用以下 URI：

http://<server>:<port>/iserver/services/{component}/rest/maps/World Map/image.bmp

返回结果为一张 bmp 格式的图片。

  • GIF 格式的表述

返回请求的 GIF 格式图片，仅当资源是图片时有效。

例如，要获得名为 World Map 的地图的当前显示，格式为 GIF，可以用以下 URI：

http://<server>:<port>/iserver/services/{component}/rest/maps/World Map/image.gif

返回结果为一张 gif 格式的图片。

  • JPG 格式的表述

返回请求的 JPG 格式图片，仅当资源是图片时有效。

例如，要获得名为 World Map 的地图的当前显示，格式为 JPG，可以用以下 URI：

http://<server>:<port>/iserver/services/{component}/rest/maps/World Map/image.jpg

返回结果为一张 jpg 格式的图片。

  • JPEG 格式的表述

返回请求的 JPEG 格式图片，仅当资源是图片时有效。

例如，要获得名为 World Map 的地图的当前显示，格式为 JPEG，可以用以下 URI：

http://<server>:<port>/iserver/services/{component}/rest/maps/World Map/image.jpeg

返回结果为一张 jpeg 格式的图片。