FRAMES | NO FRAMES

 

B U S I N E S S   A N A L Y S T   10.5  R E S T   R E S P O N S E   F O R M A T S

Business Analyst Server REST Response Formats

Business Analyst Server and Business Analyst Online REST 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 Business Analyst Server REST 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 for the response formats available for each endpoint.

 

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

 

XML 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 whitespace is unnecessary and ignored by JSON parsers. Additionally, PJSON data, with all of its whitespace, 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 Business Analyst Server and Business Analyst Online REST. While it may not be useful as a data interchange format, it may be useful for developing and testing applications with Business Analyst Server REST endpoints. 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.

Error Response Format

If a Business Analyst Server REST endpoint fails to execute a request, a special error object is returned.

 

In Business Analyst Server, an error object has the code, message, and details properties. In the Business Analyst web app, an error object is a string message. Below are examples of error responses retrieved in the PJSON format.

 

Business Analyst Server Error Response Example

{
"error":
  {
  "code": -2147467259,
  "message": "Failed to rename project.",
  "details": ["Error code: 0x80004005 ..."]
  }
}

 

NOTE: The response has been abbreviated where "..." is noted.

 

Business Analyst Online Error Response Example

{
"error": "(498) Token is invalid."
}

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.

Disambiguation

Do not confuse Business Analyst Server REST Report formats with the REST endpoint response formats discussed on this page. Report formats refer to the actual report documents that are generated by Business Analyst Server REST and become available through URLs which are returned in the REST responses.

 

Additionally, do not confuse the TaskResultOutput type with the REST endpoint response formats discussed on this page. TaskResultOutput is a type of data structure used in Business Analyst Server REST 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 Business Analyst Server REST response formats: XML, JSON, PJSON, and HTML.

JSON Objects as Business Analyst Server REST Parameter Values

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