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.
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),
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.
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.