In order to get the most out of REST services, a good understanding of how a REST URI is constructed and what is returned in a response is essential.
Understanding all of the general workflow steps in this page, along with a careful review of the descriptions and examples in the individual documentation pages for each service, will greatly aid in understanding REST services. After gaining a general understanding of REST services Utilization Workflow, client applications can be developed to submit requests and consume the responses.
Using the documentation, plan for and select the desired Utility Services, Standard Geography Services and Analysis/Report Services to submit. Note the descriptions, parameters, and usage in the individual documentation pages for each service. Additionally, each service has at least one complete example URI request and the returned response. These examples provide one of the best ways to quickly get up to speed with REST services.
In order to submit requests and receive responses in REST services, a valid token string must be included in any URI request. This token validates access to the service endpoints and the types of analysis which may be performed with the associated account.
Construct and submit valid account credentials with a secure Get Token Request. The response will contain a string token which will be valid for a set amount of time. While it is valid, it can be used as the Token parameter value in REST services requests.
Assemble and append valid parameter values for the URI request. This includes the value for the Token parameter, any analysis options, the REST response format, and Summary Reports options, if applicable. Make note of the required parameters, their syntax, formats, and usage notes in the individual documentation pages for the Utility Services, Standard Geography Services and Analysis/Report Services. The type of information required by each parameter will be thoroughly described alongside examples.
It is also possible to assemble and specify parameter values derived from the response output from previous REST services requests. For example, Standard Geographies By Attributes might have been used previously to get all of the ZIP codes associated with the 065 prefix (all ZIP codes for New Haven, CT). The user or client application would parse these ZIP codes from the previous service response and then immediately include them as parameter values in a new URI request. One example would be to use them in defining the analysis areas in Summary Reports.
Because REST services' feature class geometry formats conform to the geometry schema defined by ArcGIS Server, ArcGIS Server's mapping APIs and REST geoprocessing services may be leveraged alongside REST services. Polygons and points drawn in mapping API User Interfaces may be used as parameter values to certain REST services requests. The ArcGIS Server JavaScript API, Flex API, and Silverlight API have excellent documented examples of drawing toolbar components. These drawing toolbars create Geometry objects which are compatible with REST services. These geometries, which are drawn through a map interface, may be used as parameters defining an area of analysis in Analysis/Report Services such as Summary Reports. The existing ArcGIS Server tools and services should be leveraged to the maximum extent possible.
Using a client application or a Web browser (for sufficiently short URI strings---approximately 2000 characters for Microsoft Internet Explorer), submit the complete URI to the API for execution. One of the big advantages of RESTful Web services is the ability to test and submit REST requests manually through a browser before or while a client application is being developed.
REST services support different response formats for server output to the calling client or browser application. The response format is specified by including the query parameter f and a valid option in a REST services URI request. The list of supported formats for most Utility and Analysis/Report Services includes HTML (HyperText Markup Language), JSON (JavaScript Object Notation), PJSON ("prettified" JSON for readability), and XML (Extensible Markup Language). This variety of output formats can aid in the construction of state-of-the-art Rich Internet Applications, cross-platform and cross-application solutions, and applications which can be integrated with legacy systems and data.
It is recommended that client side utility libraries be leveraged to parse XML and JSON responses. Examples include the DataContractSerializer and DataContractJsonSerializer for Microsoft Silverlight and .NET 3.5-based applications; the XML class and as3corelib for Flex 3.x (ActionScript 3.x)-based applications; numerous other JSON utility libraries listed at www.json.org for applications built on a variety of platforms/systems and in different programming languages; and a multitude of XML utility libraries in search engine results for AJAX libraries for JavaScript-based applications.
For more details, see Output Formats and the documentation for the individual Analysis and Utility services.
Summary Reports analysis is a significant and valuable part of what REST services offer. Based on the request, the output response can contain links to one or more Summary Reports.
As implied in the discussion in Step 3 above, ArcGIS Server's mapping APIs can be leveraged as a vehicle to display output feature classes such as the polygon results of Drive Time or Simple Rings, or polygons for "named areas" such as ZIP codes, counties, Census Tracts, etc. in Summary Reports. ArcGIS Server's mapping APIs are highly recommended for creating User Interfaces (UIs) for Rich Internet Applications (RIAs) which leverage Business Analyst's rich data and powerful analyses.