浅析 AGS REST API

 表述性状态转移（REpresentational State Transfer）简称REST，REST软件架构由Roy Thomas Fielding博士在2000年首次提出，我们可以从他的论文中看到关于REST的详细描述：

英文： http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
中文： http://e2c.91yee.com/posts/show/186

    如何将REST解释清楚，InfoQ上有两篇文章： 深入浅出REST、 理解REST软件架构。

    还有IBMDeveloperWorks上也有一些文章，就不一一列举了，初次接触REST的可以先看看《深入浅出REST》，有兴趣可以Google/Baidu查找更多的相关资料，特别是Fielding博士的论文。直接通读理论有时难免会有些晦涩，而将理论放到实际应用中往往可以得到更好的理解，因此这里我不去讲解REST是什么（我自己还在学习中），但可以先记住《深入浅出REST》中总结的REST五条关键原则：

*为所有“事物”定义ID
*将所有事物链接在一起
*使用标准方法
*资源多重表述
*无状态通信

    ArcGIS Server 9.3（简称Ags93）提供了全新的REST API，实现了一些Ags通用功能和服务便于Ags客户端开发，如javascript api。安装了Ags93之后，可以通过 "http://<host>/<instance>/services/<folder>"方式来访问服务的根目录，其中"instance"默认为"arcgis/ rest"，里面列举了当前服务器上所有已启动的server服务，并且可以将这些服务列表导入Google Earth，格式为kmz。REST访问地址中，folder和servicename是对大小写敏感的，folder前面的部分则没有影响。

    点击根目录列举的一个服务，页面会展示该服务的所有基本信息，包括地图图层，图层编号，空间参考，部分cache信息，初始化地图显示范围，地图全图显示范围，地图单位，MXD文档基本信息。


    同时，还可以选择将该服务放置在哪一种客户端（平台）上显示，ArcGIS JavaScript链接为：
http://localhost/ArcGIS/rest/services/beijing/MapServer?f=jsapi

    这为Ags Javascript API访问REST API提供了一种途径，其他的客户端都可以用"f"这个参数来指定。

    REST里所描述的服务，包含资源和操作两种类型，上面所说的是资源，就是描述该服务的一些属性信息，操作指的是基于该服务能够实现的功能，如导出地图、查询、搜索、生成KML。

    资源和操作的整体框架：


    每一种资源都有统一的URI来标识，资源通过链接被相互关联在一起，如MapService下的各种操作功能，并且资源有多重表述方式，如希望地图服务返回图片，可以在URI指定参数"f=image"，返回在ArcMap中浏览的图层文件，指定"f=lyr"，返回在javascriptapi客户端浏览的网页，指定"f=jsapi"等等，这些都取决于我们的应用和需求。这种框架结构粗看有点ArcXML的感觉，实际上它体现了更多的语义，如何在javascript api调用这些资源，两个文档中的简单例子：

    添加一个cache地图： myTiledMapServiceLayer =
new esri.layers.ArcGISTiledMapServiceLayer( " http://servery.esri.com/arcgis/rest/services/maps/world/MapServer " );
myMap.addLayer(myTiledMapServiceLayer);
    对图层构建查询功能：
function init() {
// build query
myQueryTask =
new esri.tasks.QueryTask( " http://servery.esri.com/arcgis/rest/services/maps/world/MapServer/1 " );
. . .
    Ags Javascript API基于REST API构建，其消息是通过JSON格式进行传递的，如
http://localhost/arcgis/rest/services/maps/world/MapServer/export?bbox=-197.99999664046,-131.792384313038,197.99999664046,125.388423131397&f=json

    其返回的格式为：
{"href" : "http://servery.esri.com/arcgisoutput/_ags_map26163878476945a499cd7521135dd581.png","width" : 400,"height" : 400,"extent" :{"xmin" : -197.99999664046,"ymin" : -201.201977231281,"xmax" : 197.99999664046,"ymax" : 194.79801604964,"spatialReference" :{"wkid" : 4326}},"scale" : 4.16060604668823E8}
    看起来比较杂乱，如果需要阅读性比较好的JSON，需要指定参数"f=pjson"或"f=json&pretty=true"，但这样会影响性能，只建议在debug阶段使用：
{
"href" : "http://myserver/arcgisoutput/_ags_mapabab6b08a05a4bf6b1f4047a20ba136b.png",
"width" : 400,
"height" : 400,
"extent" :
{
"xmin" : -197.99999664046,
"ymin" : -201.201977231281,
"xmax" : 197.99999664046,
"ymax" : 194.79801604964,
"spatialReference" :
{"wkid" : 4326}
},
"scale" : 4.16060604668823E8
}
    重复REST五条关键原则：

*为所有“事物”定义ID
*将所有事物链接在一起
*使用标准方法
*资源多重表述
*无状态通信

    理论的研究经常伴随着复杂、严谨、全面，其实要表达的有时是很简单的道理，慢慢琢磨Ags REST API，会对REST理论有更深入的体会，了解REST，也能更清晰看到Ags REST API的设计结构。