Skip to content

RationalBI API (1.0.0)

Download OpenAPI specification:Download

Rational BI Support: support@rationalbi.com

The Rational BI API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. You can use the API to create and manage datasets, reports and data. The most typical use-case of the API is to programatically upload data into pre-created datasets for use in reporting. To do this, see the "Upload a database" API call.

Datasets, schemas and databases

Datasets

The API allows interaction with the basic building blocks of the Rational BI pipeline. Generally, data is contained within datasets that act as container objects of a certain named set of data, most easily visualized as a relational database with multiple tables.

Schemas

Datasets allow multiple schemas in order to allow the data in the dataset to evolve over time without breaking compatibility with existing reports. Whenever breaking changes are to be introduced to the table and column structure, a new schema can be introduced. Datasets can contain any number of concurrent schemas.

Databases

Databases are attached to schemas and are represented as relational SQL databases in SQLite format, conforming to the format of the selected schema.

Resources and UUIDs

Resources in Rational BI are identified by unique ids (UUIDs). UUIDs are automatically allocated for most resources and primitives known by the system. The identifiers are strings, typically 34 characters in length. The first two characters can be used to identify the type of resource referenced.

Prefix Type
re Report
us Interactive (Normal) User
ux API User
db Database
gr Group
lo Organization Logo
po Security Policy
pp User profile picture
pr Password recovery token
or Organization
ac Account
da Dataset
ds Schema

Returned UUIDs are static for the lifetime of the object and can be stored for later reference to objects.

Authentication

Session

Most API calls requires authentication in the form of a session id that can be obtained through the Session API call. You can either just call the Session API and allow the supplied cookie to be set, or store the session ID separately and resupply it to the server in the form of a header (X-Session)

Security Scheme Type API Key
Header parameter name: X-Session

Administration

Administrative operations not related to data. Use the create session API call to authenticate to the API prior to calling other methods.

Get API version

Retrieves the current versions of the API. This method is mostly intended as an echo test of API connectivity.

Responses

Response samples

Content type
application/json
{
  • "sessionId": "string"
}

Create API session

Create a new API session (sign in). If an existing session exists, reattach the existing session.

Request Body schema: application/json

Required credentials. In the typical case, only email and password are required. API users should submit user UUID and password instead.

email
string

User email

password
string

User password

uuid
string

UUID associated with an API user

twoFactorTotp
string

TOTP code. The server will respond with a response code to indicate that TOTP data should be supplied, if required.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "uuid": "string",
  • "twoFactorTotp": "string"
}

Response samples

Content type
application/json
{
  • "majorVersion": 1,
  • "minorVersion": 0
}

Delete API session

Delete the current session (sign out). After deleting the session, the session ID will no longer be valid.

Authorizations:

Responses

Response samples

Content type
application/json
{ }

Check disk quota

Check if the organization has sufficient space to store a database of specified size. Some subscription plans have a limit to the total amount of data that can be stored. This method allows a user interface to check that a future upload is likely to be accepted before creating a new dataset and schema to hold the data.

Authorizations:
path Parameters
uuid
required
string

UUID of the organization to query.

query Parameters
size
required
integer

Size in bytes of the data to upload

Responses

Response samples

Content type
application/json
{
  • "error": "no_session",
  • "message": "You must authenticate prior to using this method"
}

Datasets

Datasets are virtual databases. They encapsulate the concept of a named datastore that contains data that can be used in reporting. It can encapsulate a single CSV file, a multi-sheet Excel file or a complex multi-table relational database structure that projects data from a corporate data store. The data in a dataset can be represented by physical and virtual data, either as uploaded relational database (that can have been converted from source files such as Excel or CSV files) but it is also possible have the data in a dataset be a virtual connection to a remote data store.

Get available datasets

Get an list of available datasets. Each item in the list contains abbreviated information about the dataset, suitable for identifying and rendering in a list in a user interface.

Public datasets

This method can also search for public datasets, i.e. those that have been flagged by other customers as shared.

Authorizations:
query Parameters
search
string

Search string to filter the list of returned datasets. This string is a case insensitive substring search on fields such as title and description.

sharing
string

Filter by sharing status. Possible values are public or none.

count
integer
Default: 100

Maximum number of results to return.

offset
integer
Default: 0

Starting offset of results to return. Can be used to implement pagination of results.

Responses