Business Analyst Server REST Workflow

Getting Started with Business Analyst Server REST

Introduction

In order to get the most out of Business Analyst Server REST, a good understanding of how a Business Analyst Server 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 task, will greatly aid in understanding Business Analyst Server REST. After gaining a general understanding of Business Analyst Server REST Utilization Workflow, client applications can be developed to submit requests and consume the responses.

Business Analyst Server REST Utilization Workflow

Select an Endpoint

Using the documentation, plan for and select the desired Business Analyst Server REST endpoint to submit. Note the descriptions, parameters, and usage in the individual documentation pages for each endpoint. Additionally, each endpoint 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 Business Analyst Server REST.

Obtain a Token

If your Business Analyst Server is secured, you need to get a valid token from the associated ArcGIS Token Service endpoint. The received token string must be included in any URI request. This token validates access to the service endpoints and the types of analysis which can be performed with the associated account.

Construct and submit valid account credentials with a secure Get Token request. The response will contain a token string which will be valid for some time. While it is valid, it can be used as the token parameter value in Business Analyst Server REST URI requests. See Using Secured Business Analyst Server Web Services for details on obtaining an authentication token.

Append Parameter Values

Assemble and append valid parameter values for the URI request. This includes the REST response format, an unexpired token parameter if your Business Analyst Server is secured, and specific parameters for an endpoint. In many cases, JSON structures are used for specifying Business Analyst Server REST parameter values. Unlike the response format, the parameter values cannot be represented in other formats such as XML.

Make note of the required parameters, their syntax, formats, and usage notes in the individual documentation pages for Business Analyst Server REST endpoints. The type of information required by each parameter will be thoroughly described alongside examples.

It is possible to assemble and specify parameter values derived from the response output from previous Business Analyst Server REST requests. For example, the StdGeographiesByAttributes endpoint 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 task's response and then immediately include them as parameter values in a new URI request.

Because Business Analyst Server REST's feature class geometry formats conform to the geometry schema defined by ArcGIS Server, ArcGIS Server's mapping APIs and REST geoprocessing tasks and services may be leveraged alongside Business Analyst Server and Business Analyst Online REST. Polygons and points drawn in mapping API User Interfaces may be used as parameter values to certain Business Analyst Server REST 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 Business Analyst Server REST. The existing ArcGIS Server tools and services should be leveraged to the maximum extent possible.

Submit the URI Request

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 Business Analyst Server REST endpoint 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.

Parse, View, and Interact with the Response

Business Analyst Server REST supports 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 Business Analyst Server REST URI request. The list of supported formats for most endpoints includes HTML (HyperText Markup Language), JSON (JavaScript Object Notation), XML ("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 Business Analyst Server REST Response Formats and the documentation for the individual endpoints.

As implied in the discussion above, ArcGIS Server's mapping services can be leveraged as a vehicle to display output feature classes such as the resulting polygon and point record sets received with the TaskResultOutput structure. ArcGIS Server's mapping services are highly recommended for creating User Interfaces (UIs) for Rich Internet Applications (RIAs) which leverage Business Analyst Server's rich data and powerful analyses.