The Services Directory and the REST API

ArcGIS Server offers a way to discover information about services available at a particular server. This is known as the Services Directory. It is available as part of the REST services infrastructure available with most ArcGIS Server installations. The Services Directory enables users to list the services available, including secured services when a proper login is provided. For each service, a set of general properties are displayed. For map services, properties include the spatial extent, spatial reference (coordinate system) and supported operations. Layers are also listed, with links to details about layers, which includes layer fields and extent. Simple queries may also be executed on layers.

Some ArcGIS Server installations may not allow access to the Services Directory. In this case, contact the administrator of the site for information about the services you want to use in your application.

Opening the Services Directory

To open the Services Directory for an ArcGIS Server machine, you must know the URL of the server instance. In a typical install of ArcGIS Server, the instance is installed in the web server's root as "arcgis". The Services Directory is in the "rest" folder inside the instance. For example, if the server is at www.example.com, the Services Directory would typically be at http://www.example.com/arcgis/rest/services. Contact the administrator of the ArcGIS Server system if you are uncertain about the server URL or ArcGIS instance.

Getting information about a service in Services Directory

You may use the Services Directory to obtain information you need to use a service with the ArcGIS JavaScript Extension for Virtual Earth. The URL to a service may be copied from the location box in your browser. For example, a service in the example server cited above might have a URL of http://www.example.com/arcgis/rest/services/ExampleService/MapServer. Notice the server type appended to the end of the URL. This is required to specify the type of service used.

Other useful information may also be obtained. For example, to identify features within particular layers, the IDs of the layers must be used (see the walk-through Identify or find features near a location). The IDs of layers (typically integers) are listed with the Layers list in a map service's properties page. If you need names of attribute fields to specify the information to return in a query, you can drill down to the layer's properties to find a list of fields.

If you are using the Services Directory to locate services to use, note that map services must meet certain criteria in order to be used with the Virtual Earth extension. Important aspects are that the map must have a spatial reference of 102113 (Web Mercator) and must have a "Single Fused Map Cache". For details on service requirements, see Creating services for the ArcGIS JavaScript Extension for Virtual Earth.

Services and folders may be secured so that only authorized users may access them. If a service or folder does not appear as expected, it may require a login. If the server administrator has provided a username and password to you, click the Login link in the Services Directory and log in to see services permitted to you. For more information, see Working with secure ArcGIS services.

About the REST API

The ArcGIS Server REST API provides a relatively simple way to use services provided by ArcGIS Server. REST enables use of web resources by encapsulating information in the URL and query string of the request. It has become popular when combined with the technology known as AJAX for creating dynamic client-side web applications.

ArcGIS Server includes a REST API for accessing services. A reference for the REST API is available online. The REST API supports most of the functionality available in the ArcGIS Server SOAP API, which is used in the server-side Web Application Developer Framework (ADF) packages for ASP.NET and Java. The difference is that the REST API enables creation of applications that are strictly client-side. Most REST API-based applications will likely be focused, simple applications of ArcGIS Server technology. The ArcGIS JavaScript Extension for Virtual Earth uses the REST API to communicate with services in ArcGIS Server. The REST API is used in other APIs available with ArcGIS Server, including the stand-alone ArcGIS Server JavaScript API and the ArcGIS JavaScript Extension for Google Maps.

Working with JSON

The REST API returns data in JavaScript Object Notation (JSON). Generally you do not need to interact directly with JSON-formatted data, because the ArcGIS JavaScript Extension for Virtual Earth automatically translates data into Virtual Earth objects. Occasionally, however, you may have to work with JSON objects. Fortunately, modern browsers have built-in support for working with JSON. You can handle JSON objects with JavaScript.

JSON packages data as name-value pairs, with the general format {name : value }. The value can be a number of types, including a string, a number, or an array. An example of a JSON object with an array would be: {"fruits" : ["apple", "orange", "banana"]}. Each value can itself be a JSON object. A JSON object can contain multiple name-value pairs, so that a complex description of data can be communicated.

Let us look at an example. The text below is part of the JSON object for a map service in the REST API. The mapName has a value of "Layers". There is one item in the "layers" value array; this item is its own JSON object, with five items (id, name, parentLayerId, defaultVisibility and subLayerIds).

{
  "serviceDescription" : "", 
  "mapName" : "Layers", 
  "description" : "", 
  "copyrightText" : "", 
  "layers" : [
    {
      "id" : 0, 
      "name" : "KS_FIELD_OUTLINES_SPRING2005_GEONAD27", 
      "parentLayerId" : -1, 
      "defaultVisibility" : true, 
      "subLayerIds" : null
    }
  ], 
  "spatialReference" : {
    "wkid" : 4326
  }, 
...
}

Say you want to retrieve this information about a map service and display it in the browser. The ArcGISLayerFactory class returns this JSON-formatted map service information in both its CreateLayer and GetResourceInfo methods. When you call either of these methods, you pass the method the name of a function (callback function) that will receive the actual data. Below is an example of a function that receives the JSON data as a result of GetResourceInfo. This function gets several pieces of information about the map service and displays the information within a <div> in the HTML page.

function showResourceInfo(sender, resourceInfo) {
   if (resourceInfo==null) resourceInfo = sender;

   var mapName = "Map name: " + resourceInfo.mapName + "<br/>";
   var spatialRef = "Map coordinate system ID: " + resourceInfo.spatialReference + "<br/>";
   var layers = resourceInfo.layers;
   var layerInfo = "";
   for (var i=0; i<layers.length; i++) {
      layerInfo += "Layer " + layers[i].id + " name: " + layers[i].name + "<br/>";
   }
            
   document.getElementById("ResourceInfoDisplay").innerHTML = "Map service information: "
     + mapName + spatialRef + layerInfo;
}

Notice that you can reference the JSON objects directly using JavaScript. For example, the layers collection was one of the objects in the JSON data we saw in the map service description above. We can access this in the page by referencing resourceInfo.layers. Then since the layers is an array, we can access each layer in the collection using JavaScript. The only difference from working with other objects in JavaScript is that you must know the names of the objects within the JSON object. You can obtain this information either by step-through debugging tools, or by obtaining documentation about the objects, such as by examining the service information in the Services Directory as discussed above in this page.