RationalBI API (1.0.0)
Download OpenAPI specification:Download
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
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 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.
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 |
Administrative operations not related to data. Use the create session API call to authenticate to the API prior to calling other methods.
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.
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
- Payload
{- "email": "string",
- "password": "string",
- "uuid": "string",
- "twoFactorTotp": "string"
}Response samples
- 200
- 401
- 403
- 404
- 412
- 422
- 423
- 500
{- "majorVersion": 1,
- "minorVersion": 0
}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
- 200
- 401
- 403
- 404
- 412
- 422
- 423
- 500
{- "error": "no_session",
- "message": "You must authenticate prior to using this method"
}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. |