Using a REST server object extension in a client application

About REST server object extensions in client applications

Once you’ve deployed your REST server object extension (SOE) in Manager and enabled it on a service, you can begin the process of building a client application for it. Because you’ve built your SOE as a web service, it takes in simple types, such as strings, doubles, and so on. About the most complex thing you might submit to your SOE is a JavaScript Object Notation (JSON) object representing a set of geometry vertices.

Testing the SOE in the services directory

The fact that you submit simple types to your web service allows you to test your SOE in the Services Directory. After enabling the SOE on your map service, navigate to the map service’s page in the Services Directory. At the bottom of the page, you’ll see the SOE listed under Supported Extensions. (If you don’t see it, verify the ArcGIS Server administrator has cleared the REST cache.)
If you click the SOE in the Services Directory, you’ll be able to click and explore the resources and operations you exposed. Click an operation and you’ll see some input boxes that you can use to test the SOE requests and responses. You should get back a simple JSON or Hypertext Transfer Markup Language (HTML) response.

Writing a client application for the REST SOE

No matter which application programming interface (API) you use, working with your SOE web service requires the following:
  • Making a request from the web service—Involves building a list of parameters and sending the completed uniform resource locator (URL) to the server.
  • Doing something with the response—Requires understanding the format of the response and knowing how to parse the information to do something useful in your application.

Working with REST SOEs in the ArcGIS API for JavaScript

If you’re developing with the ArcGIS API for JavaScript, you’ll use esri.request() to make the web service request. You first set up a JSON object containing all the parameters of the request, then you pass that content object to esri.request, and define the URL of the SOE and a handler function that does something with the result. The result is a simple JavaScript object.
The following code example shows an SOE being used from the ArcGIS API for JavaScript:
[JavaScript] 
var soeURL = 
    "http://myServer/ArcGIS/rest/services/Yellowstone/MapServer/exts/SpatialQuerySOEREST/SpatialQuery";
. . . var content = {
    'location': "{x:" + point.x + ",y:" + point.y + "}", 'distance': distanceNumber,
        'f': "json"
};
// Do the SOE query.
esri.request({
    url: soeURL, content: content, callbackParamName: "callback", load: function
        (response){
        drawResponseGeometries(response.geometries); responseRecordsToGrid
            (response.records); 
    }
    , error: function(error){
        console.log(error); 
    }
}

);
. . .
In the previous code example, the SOE requires the parameters location, distance, and f (format). These parameters are derived from user interaction with the web form (not included here) that sets values for the point and distanceNumber objects. The content object uses this information to set up all the required parameters in JSON format.
Once the content is prepared, the code makes a request to the SOE using esri.request(). Notice that this requires the URL of the SOE’s REST endpoint.
Also, you must define a callback function that determines how to use the response. The response from this particular SOE includes the following JSON objects to work with:
  • Geometries
  • Records
Helper functions (not shown here) take the response and put it onto the map as graphics (in the case of the geometries) and into a table (in the case of the records).

Working with REST SOEs in the ArcGIS API for Flex

In the ArcGIS API for Flex, you use your SOE through extending the BaseTask class. The url property on BaseTask should point at the SOE. You can then use the BaseTask's sendURLVariables method to make the request to the web service. The response is a Flex object from which you can access the different JSON objects returned in the response.

Working with REST SOEs in the ArcGIS API for Silverlight

With the ArcGIS API for Silverlight, you consume SOEs by following standard Silverlight practices for making web service requests and working with JSON responses. These are detailed in the following Microsoft Help topics:
You can find more detailed examples about working with SOEs in the JavaScript, Flex, and Silverlight APIs by examining the help system for the specific API of your interest.