B U S I N E S S   A N A L Y S T   10.5   R E S T   I N T E R F A C E

Business Analyst Server REST Request Format

Parameters of Business Analyst Server REST endpoints are described using the following template:

The left column specifies a parameter name and an optional requirement for this parameter—the (required) value means that this parameter must be specified and the (optional) value means that this parameter can be omitted in the query. An optional parameter can have a default value which is specified in the parameter description. If the requirement is omitted, the presence of the parameter in the query depends on values of other parameters. The details and relations between endpoint parameters are described in the Remarks section of a endpoint description topic.

For convenience, parameters of many endpoints are grouped into two tables—the first table contains endpoint-specific parameters and the ssecond table specifies other parameters which are common for endpoints having the similar functionality.

Parameters of Business Analyst Server REST endpoints are passed in the query part of a request URI using the name=value syntax:

?{name}={value}&{name}={value}...

A parameter value is represented in the query as a string or as a JavaScript Object Notation (JSON) structure depending on a parameter type. In the scope of this documentation we designate the following datatype categories:

• Primitive type is a build-in datatype specified in XML Schema Part 2: Datatypes Second Edition.

• Simple type is a type whose value is represented in the query with a string literal.

• Complex type is a type whose value is represented in the query using a JSON object.

• Array of primitive or simple type is a type whose value is represented in the query as a list of literals delimited with ';' character.

• Array of complex type is a type whose value is represented in the query as a JSON array.

NOTE: Whitespace in the parameter values of the query may be substituted with the '+' character (e.g. "My+Report+Subtitle"). URL encoding also allows the use of '%20' in place of spaces.

Primitive Types

The following primitive types are used in this documentation.

Simple Types

In Business Analyst Server REST, a simple type is represented with a string literal whose value can be one from a set of literals specified in the type definition. The definition of a simple type looks as follows.

xs:simpleType name="type-name"

The name attribute value of the simple type specification identifies a type name. The definition table contains the enumeration of allowed string literals and their descriptions.

A value of a simple type is specified in the parameters of a query by the same rules as a string value—when used as a parameter value, a simple type value is not enclosed in quotation marks, but, when used in JSON objects, a simple type value is enclosed in quotation marks.

Complex Types

In Business Analyst Server REST, a complex type represents a data object containing properties. Every property is a name/value pair whose name is specified in the left column of the type definition table and the type of value is described in the right column. The definition of a complex type looks as follows.

xs:complexType name="type-name" base="type-name"

The name attribute value of the complex type specification identifies a type name. An optional base attribute identifies a base type that the complex type inherits properties from.

A complex type is specified in a query parameter value using the JSON syntax:

{
    "name" : value,
    ...
}

A string before a semicolon specifies a property name and a value object after a semicolon specifies a property value. String values and simple-type values must be enclosed in quotation marks. Values of other primitive types are not enclosed in quotation marks. Properties of a data object are delimited with commas.

NOTE: JSON objects in query parameter values are specified in one line. All unnecessary spaces can be omitted.

Array Types

In Business Analyst Server REST, arrays with homogeneous content are used. For example, array of double contains values of the double type only. We designate array of a primitive or simple type and array of a complex type. Their representation as query parameter values differs.

Array of a primitive or simple type is represented in a query parameter value as a string containing a list of values delimited with the ';' char. Example:

Radii=1;3;5

Here 1;3;5 is a string representation of an array consisting of 3 numeric values—1, 3, and 5.

NOTE: If an array of a simple type is a part of a complex type, it is represented in query parameter values using the JSON array syntax as described below.

Array of a complex type is represented in a query parameter value with the JSON array structure:

[
    complex-type-value,
    ...
]

Array values are delimited with commas.

NOTE: JSON arrays in query parameter values are specified in one line. All unnecessary spaces can be omitted.