Consuming SOE through REST

Applications can consume RESTful services in one of two ways, programmatically or in a web browser.  ArcGIS Server provides a Services Directory to easily access REST based services.  RESTful SOE's are automatically listed and accessed through this directory once developed and deployed to ArcGIS Server for Java. 

The ArcGIS Server REST API provides a simple, open Web interface to services hosted by ArcGIS Server. All resources and operations exposed by the REST API are accessible through a hierarchy of endpoints or Uniform Resource Locators (URLs) for each GIS service published with ArcGIS Server.  When using the REST API you typically start from a well known endpoint which represents a server catalog.  The default start URL for ArcGIS Server for Java is

Which renders an output similar to the following screenshot: 

To go to the root directory of ArcGIS Online Services, the URL is:

The resource and operation hierarchy of an SOE is based on the schema specified by the SOE.  From the REST API, this schema is available by specifying a query parameter f=schema on the root SOE resource:

Let's look at a few example schemas to understand how one specifies the resource and operation hierarchy.

Schema 1 - SOE with 1 operation

{
  "operations" : [ "buffer" ]
}

In the simplest case, an SOE exposes a single operation. From the perspective of the REST API, this SOE exposes 2 URLs - the root SOE resource and the buffer operation:

Schema 2 - SOE with multiple operations

{
  "operations" : [ "buffer", "near" ]
}

Since the operations property in the schema is an array, one can specify multiple operations. From the perspective of the REST API, this SOE exposes 3 URLs - the root SOE resource and the buffer and near operations:

All SOEs will minimally support a root resource and optionally, child resources if the SOE schema specifies them. The REST handler always requests a JSON representation for resources from the SOE. If REST clients request a resource with f=json, the JSON as returned by the SOE is sent to the client. On the other hand, the Services Directory view of this resource consumes the JSON sent by the SOE and transforms it into HTML that can be shown on a web page.

In Schema 3, layers is specified as a collection child resource of the root SOE resource. Let's assume that the JSON for the root resource returned by the SOE is as follows:

{
  "description: "Contitental US",
  "extent" : { "xmin" : ..., "ymin" : ..., ...},
  "spatialReference" : {...},
  ...
 
  "layers" : [
    { "id" : 0, "name" : "Cities", ... },
    { "id" : 1, "name" : "Counties", ... },
    { "id" : 2, "name" : "States", ... }
  ]
 
  ...
}

When displaying this as HTML in the Services Directory, the REST handler finds a layers property. Since the schema specifies this as a collection child resource, it first inspects if the value of this property is a JSON array. Further if each element in the array is a JSON object with an id and a name property, it displays a link using the name for display and the id in the URL. e.g. The Cities layer above gets the URL:

In the Services Directory, the list of layers appears as shown below.

SOE method calls for resources

Accessing a SOE resource from the REST API actually incurs a call to the handleRESTRequest method on the IRESTRequestHandler interface of the SOE. For resource requests, the operationName parameter of this method will be an empty string (""). Whereas the resourceName parameter will be a string relative to the root SOE resource. Let's revisit Schema 3 and take a look at how requests for various REST resources translate into values of the resourceName parameter when calling handleRESTRequest . 

http://<service-url>/exts/<extensionName>  "" //empty string
http://<service-url>/exts/<extensionName>/metadata  "metadata"
http://<service-url>/exts/<extensionName>/layers/1  "layers/1"
http://<service-url>/exts/<extensionName>/layers/1/features/37  "layers/1/features/37"

SOE developers are expected to be aware of this and return the resource representations based on the resourceName parameter.