Developing SOE REST Web Services

Summary This document is intended to familiarize the developer with the relevant objects and concepts related to exposing SOE's as REST Web Services. We will first introduce concepts required to gain an understanding of the objects you work with when developing SOE's as REST Web Services then work through the tools provided in the Eclipse plug-in to help simplify the development experience. After reading this topic you will be able to expose SOE's as REST Web Services.

Developing SOE REST Web Services

In order to expose your Server Object Extension (SOE) as a REST Web Service you must implement the IRESTRequestHandler interface. 

Implement IRESTRequestHandler

All SOE REST Web Services must implement the IRESTRequestHandler interface.  The interface provides two methods: 
  1. handleRESTRequest()
  2. getSchema()
IRESTRequestHandler.handleRESTREquest() method
The handleRESTREquest() method serve's two types of REST requests:
  1. Requests to invoke operations on a resource
  2. Requests to obtain instance-level descriptions of a resource
As a SOE developer, you need to distinguish between the two requests.  By convention an empty String value for the 'operationName' argument indicates the request is of type 2 above, otherwise it is of type 1 above. 
A short description of the handleRESTREquest() arguments are as follows:
  1. String capabilities: A list of operations the caller is authorized to perform on a resource. This argument can be and empty String if the request is of type 2 above. 
  2. String resourceName: A string representing a resource by its name. An empty string value (“”) indicates the root level resource. Child resources in the resource tree will be identified by a ‘/’ separated string value leading up to the name of that particular resource from the root resource.
  3. String operationName: The name of an operation to be invoked on a resource identified by resourceName.  This argument can be and empty String if the request is of type 2 above. 
  4. String operationInput: A JSON string representing the input arguments of an operation.
  5. String outputFormat: The output response format requested by the client. E.g, JSON, AMF, etc.
  6. String[] responseProperties: A comma separated list of key value pairs processed by the REST handler.
IRESTRequestHandler.getSchema() method
The getSchema() method is called by the REST handler to obtain a schema for your SOE's resource heirarchy.  The schema is always described in JSON formatted String. 

Schema

The resource and operation hierarchy of an SOE is based on the schema specified by the SOE. The REST handler invokes the getSchema() method on the IRESTRequestHandler interface to get the SOE schema. This schema is returned as a JSON formatted string. From the REST API, this schema is available by specifying a query parameter f=schema on the root SOE resource:

Resources

All SOEs will minimally support a root resource and optionally, child resources if you choose to implement 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.
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.

Web Service Tools

The ArcObjects Java Developer Kit provides an Eclipse plug-in which offers all the tooling required to develop SOE REST Web Services.
To get started using the SOE REST Web Service tooling, first install the ArcObjects Eclipse Plug-in as all tooling is provided with the ArcObjects Developer Kit and Eclipse plug-in.  Once installed, you can create a Java Project inside of Eclipse and use the ArcGIS Extension SOE template to create your SOE.  With REST Supported SOE's, creating a custom interface is optional but as with all SOE's, good pattern to use. 
REST supported SOE"s support Fast Map Services, MSD's.  To enable this feature click appropriate check box for Support Fast Map Services. 
After clicking 'Next >', the following dialog has two tabs, 'Web Support' and 'Web Capabilities'.  If you select 'Enable REST Support' the generated SOE class will implement the IRestRequestHandler interface as described above.  Additionally, the required root resource will be created for you under the 'Manage Resources' section. 
Invoking an SOE operation from the REST API also incurs a call to the handleRESTRequest method on the IRESTRequestHandler interface of the SOE. For operation requests, the Name parameter of this method will be a non-empty string. The parameter will continue to be a string relative to the root SOE resource.  You can also define the expected return type by checking the box(es) that are appropriate.  When developing SOE's for REST exposure you are expected to be aware of these parameters and invoke the appropriate logic based on the combination of the values you set here.   
After clicking 'Next >', the following dialog allows you to add properties to your SOE and choose to generate a Visual Java class to edit properties in ArcCatalog. 
Clicking Finish will generate your SOE ready for REST Web Service exposure.  At this point you are ready to implement your SOE business logic.

Deployment

Deploying your SOE SOAP Web Service is the same as deploying a typical SOE.  Please refer to the Deploying and Managing SOE's doc.