Developing SOIs

Intercepting REST, SOAP, and OGC service requests

Map and image services (including map and image service extensions, such as feature services) support three different types of requests:

In order for an SOI to intercept these requests, you need to implement the following interfaces:

All of these interfaces are found in the Esri.ArcGIS.esriSystem namespace.

Even if a particular service configuration does not support OGC requests, you need to handle all of the above interfaces. Depending on the business logic you are implementing there are two general approaches you can take. If you are implementing an SOI that will perform security functions, then it is recommended that you begin by implementing all the above interfaces and blocking all requests. As you implement your custom code, you can logically allow access through the above interfaces. If you do not initially block incoming requests and subsequently allow access as desired, you run a greater risk of inadvertently exposing a security hole. If you are not implementing security functionality, you could implement the three interfaces by passing all requests through to the underlying standard implementation in order to allow normal functionality and then subsequently add additional business logic to the one or more operations you wish to enhance.

When a service has been configured with an SOI, the server framework routes all service requests to the SOI. It is the responsibility of the SOI to process the requests, delegate the request to the actual map or image service objects if applicable, and then optionally further process the response before returning it to the client.

Implementing the IRESTRequestHandler interface

Handling the REST API is the easiest way to get started with an SOI, as all the operation parameters and responses are text/json and can be easily logged to disk.

This interface primarily contains the function:

public byte[] HandleRESTRequest(string capabilities, string resourceName, string
    operationName, string operationInput, string outputFormat, string
    requestProperties, ref string responseProperties);

The function models the REST API in terms of resources and operations and its corresponding request properties. The operationInput parameter typically contains a JSON object that represents the input. You can easily filter this object using a JSON library available in the platform of your choice. In order to get the default configuration for the service, the REST Services Directory invokes this operation by passing in empty JSON objects for all arguments. By delegating this call to the underlying service and then manipulating the output in the SOI, you can impact what resources (layers) and operations (export, find, identify, etc.) that are presented the the Services Directory and clients.

Another function that must be handled is:

public string getSchema()

This function informs the REST Services Directory how to represent the service configuration. Typically, your SOI implementation should delegate this call to the underlying map or image service object and then optionally manipulate the output as desired.

Implementing the IRequestHandler2 interface

The implementation of this interface is more involved as it handles binary requests (from ArcGIS for Desktop and other ArcObjects-based applications) and SOAP requests (from custom SOAP clients). In either case, you need to use the ArcObjects API to unpack the incoming request, optionally modify the request parameters, and then repack the request to send to the underlying map or image service objects. To post-process the responses, you’ll need to use the ArcObjects API to unpack the responses before sending it to the client. The SDK contains utility classes to assist with packing and unpacking the response objects.

This interface contains two methods that you need to implement:

public byte[] HandleBinaryRequest2(string capabilities, byte[] request)

The above function is invoked when the server receives binary requests (from ArcGIS for Desktop) for a service. The request parameter contains the binary request that must be unpacked using the ArcObjects API.

public string HandleStringRequest(string capabilities, string request)

This function is invoked when the server receives a SOAP (XML) request. SOAP clients typically make these requests. The request parameter contains the XML request that must be unpacked using the ArcObjects API.

Implementing the IWebRequestHandler interface

KML requests and OGC service requests (WMS and WFS) can be intercepted by implementing the IWebRequestHandler interface in your SOI. The functions in this interface represent a typical OGC request that is an HTTP request with query parameters. You need to implement the following function:

public byte[] HandleStringWebRequest(esriHttpMethod httpMethod, string requestURL,
    string queryString, string capabilities, string requestData, ref string
    responseContentType, ref int respDataType)

The requestData parameter is typically text/xml and contains the input for the request. However, parameters are often sent in via the queryString parameter. The respDataType parameter informs your code how the value returned byte[] must be interpreted. If the respDataType indicates a file, your code must stream the contents of the file path returned by the byte[]. The responseContentType informs the web handler about the content type to set while responding to the HTTP request.

Utility classes for working with JSON and ArcObjects-based results

A utility class called SOISupport is part of the Layer Access sample. This utility class contains methods for interacting with the parent service in order to delegate incoming requests, methods for converting between ArcObjects response objects, and much more. See the layer access sample for examples of how to use these methods particularly when dealing with SOAP and binary requests. Other classes in the ESRI.ArcGIS.SOESupport assembly provide functionality for working with JSON data and objects.