Introduction

REST services support a variety of response formats in order to offer users and developers maximum flexibility. Widely supported data interchange formats such as XML and JSON can be leveraged to create cross-platform and cross-application solutions to meet a variety of use cases.

Response Formats

Response formats for REST services endpoints are specified with the f parameter.

The currently-available response formats for all REST endpoints are string-based formats and include XML, JSON, PJSON, and HTML. Please refer to the individual documentation pages under Utility services and Analysis services for the response formats available for each service.

• Extensible Markup Language (XML) is a general purpose text-based structured data specification for data interchange.
• JavaScript Object Notation (JSON) is a newer data interchange format that is increasing in popularity since it can be evaluated by JSON parsers into native JavaScript objects (See www.json.org for a list of JSON parser libraries for several different platforms/systems).
• PJSON refers to "Prettified" JSON. It formats JSON with spaces, tabs, and carriage returns in order to improve its human readability, especially during application development and testing. All JSON request and response examples given in this documentation are represented as PJSON for readability. The PJSON response format is not recommended for actual production applications since all of the white space is unnecessary and ignored by JSON parsers. Additionally, PJSON data, with all of its white space, can be significantly larger than its JSON equivalent. This can significantly affect application performance.
• HyperText Mark-up Language (HTML) is the most popular way to describe the structure and text of a Web page and is a response format supported by the REST services. While it may not be useful as a data interchange format, it may be useful for developing and testing applications with REST services. In certain specialized use cases, HTML responses may be useful for embedding HTML-formatted data into other Web pages as frame-based content.

Default Response Format

The HTML response format is the default value of the f parameter so; if HTML output is desired, specification of this parameter is not necessary.

Response Handling

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.

JavaScript-friendly Callback Parameter

Most REST tasks support a Callback parameter. With the Callback parameter, you can wrap the entire REST JSON or PJSON response in a JavaScript function defined by the Callback parameter value. When the wrapped response is returned and a function with the corresponding name exists in the client-side code, it will be invoked and the wrapped JSON or PJSON response will be passed to it as an evaluated JSON object---no parsing or deserialization will be necessary.

Additionally, the Callback parameter is useful for making cross-domain REST requests from a client application without requiring an HTTP proxy application, using the HTML IFRAME element, or similar workaround. A simple and working sample of these concepts is provided here.

Disambiguation

Do not confuse REST services Summary Reports formats with the REST (service) response formats discussed on this page. Summary Reports formats refer to the actual report documents that are generated by the REST services and become available through URLs which are returned in the REST responses. See Get Report Templates for a list of Summary Reports options and their available report formats. Also, see an example of the TaskResultOutput type for an example of a Summary Reports output URL.

Additionally, do not confuse the TaskResultOutput type with the REST (service) response formats discussed on this page. TaskResultOutput is a type of data structure used in REST services to encapsulate and describe the execution result of a REST request in a REST response. A client application, which consumes this response, will parse the data structure for the result. The data associated with TaskResultOutput can be represented in any of the available REST services response formats: XML, JSON, PJSON, and HTML.

JSON Objects as REST Services Parameter Values

In many cases, JSON structures are used for specifying REST services parameter values. Unlike the response format options discussed on this page, the parameter values cannot be represented in other formats such as XML.

Output Format Examples

The following is a list of REST services request examples with the different response format options:

Request Example (1)

http://baoapi.esri.com/rest/report/GetReportTemplates?
&Token=ABC123...&
f=XML

Request Example (2)

http://baoapi.esri.com/rest/report/GetReportTemplates?
&Token=ABC123...&
f=JSON

Request Example (3)

http://baoapi.esri.com/rest/report/GetReportTemplates?
&Token=ABC123...&
f=PJSON

Request Example (4)

http://baoapi.esri.com/rest/report/GetReportTemplates?
&Token=ABC123...

Notes: For HTML output, specification of the response format (f) parameter value is not necessary since it is the default value.

The examples include request URIs without valid token parameter values. Include a valid token value to submit. See Get Token for more information on obtaining a token.