Introduction to the Business Intelligence REST API

Internally, the JavaScript API uses the Business Intelligence REST API, which you can also use directly, as follows:

Create a web application.
Or use the web application /api/deepsee, which is provided as part of the installation.
In your JavaScript client code, create and send HTTP requests to the desired target REST services.
If your web application uses the dispatch class %Api.DeepSeeOpens in a new tab, the target URL must include the Business Intelligence REST API version number and the target namespace name as part of the application path. It should take the following form:
```
[protocol]://[baseURL]/[appName]/[version]/[namespace]/[APIcall]
```
where [baseURL] refers to your instance, [appName] is the path which is defined as the web application’s name, [version] is the version of the REST API which you want to invoke, [namespace] is the target namespace, and [APIcall] is the actual rest call (for example, /Info/Cubes). For example:
```
https://data.mycompany.com/api/deepsee/v3/sales/Info/Cubes
```
If your web application uses the dispatch class %DeepSee.REST.v3Opens in a new tab, the REST API version number and the target namespace are implicit to the web application definition and can therefore be omitted from the target URL. In other words, the target URL should take the following form:
```
[protocol]://[baseURL]/[appName]/[APIcall]
```
For example:
```
https://data.mycompany/mycustombiapp/Info/Cubes
```
Note:

The client must accept JSON. The Accept header of the request must either specify application/json or not declare a format.
Examine the response objects and use as applicable.

Use of Slashes in Cube and KPI Names

It is relatively common to use slashes (/) in the logical names of cubes and other items, because the slash character is the token that separates a folder name from a short item name. For example, a cube might have the logical name RelatedCubes/Patients

You can directly use these logical names unmodified in URL parameters (as well as in the request bodies). The applicable Business Intelligence REST services account for logical names that include slashes. The logic, however, requires you to follow a naming convention (depending on which REST services you plan to use). Specifically, do not have an item with a logical name that is the same as the name of a folder used by another logical name. For example, if you have an item called mycubes/test/test1, you should not have an item called mycubes/test.

The reason for this restriction is that when you use a REST service that uses another argument after the logical name, part of the name is interpreted as another argument if the first part of the name matches an existing item. Consider the following REST call:

https://localhost/api/deepsee/v3/Info/FilterMembers/:mycubename/:filterspec

Here mycubename is the logical name of a cube and filterspec is the specification for a filter provided by that cube. Now consider this REST call with mycubes/test/test1 as the name of the cube:

https://localhost/api/deepsee/v3/Info/FilterMembers/:mycubes/test/test1/:filterspec

In order to interpret the slash characters, the system first attempts to find a cube named mycubes and then attempts to find a cube named mycubes/test, and so on. When the system finds the first item that matches the apparent name, the REST call uses that item, and the remainder of the string is interpreted as the next argument.

Notes on the Response Objects

For most of the REST calls, the response objects contain the property Info, which contains information about the request and response. This object contains the property Error, which equals one of the following:

Null — This indicates that no error occurred.
An object that contains the properties ErrorCode and ErrorMessage — This object contains details about the error that you can use to determine whether and how to proceed.

If no error occurred, the response object also contains the property Result, which is an object containing the requested values.

In general, your client code should first check the Info.Error property and then determine how to proceed.

For example, a response object might look like this (with white space added for readability):

{"Info":
    {"Error":
        {"ErrorCode":"5001",
         "ErrorMessage":"ERROR #5001: Cannot find Subject Area: 'SampleCube'"}
    }
}

In contrast, if no error occurred, the Info.Error property is null and the Result contains the result that you requested. For example:

{"Info":
    {"Error":"",
    "BaseCube":"DemoMDX",
    "SkipCalculated":0},
    "Result":
        {"Measures":
            [
               {"name":"%COUNT","caption":"%COUNT","type":"integer","hidden":0,"factName":""},
               {"name":"Age","caption":"Age","type":"integer","hidden":0,"factName":"MxAge"}
        ...]
    }
}

Introduction to the Business Intelligence JavaScript API