This document provides reference materials for using the dRofus REST API for data from a given database. For the database management REST API, se this: Admin system REST API

This API is providing an Open API specification describing the API. We also have an interactive GUI that lets you explore this API and try it out in the browser. Since we expose and document how to get database/project specific properties we require you to login to see the documentation. See Authentication below.

Provide feedback

Do not hesitate to contact us and provide feedback on what use cases you would like to use the API for.

URLS

The API is currently deployed to the following locations. More will follow. The API documentation will expose project specific properties so you need to log in to see it. Please see dRofus REST API#Authentication section below for how to connect with your dRofus username and password.

Authentication

OAuth2 Bearer

The dRofus API supports two OAuth2 authentication methods:

1. Authorization Code Flow

2. Client Credentials Flow

1. Authorization Code Flow

This method is suitable for web applications where a user needs to grant permission. Registration process of OAuth2 client is currently manual. Please reach out to support@drofus.com for the necessary information and provide your desired redirect_uri(s) and if desired, post_logout_redirect_uri(s).

2. Client Credentials Flow

This method is suitable for server-to-server authentication where no user interaction is required. Contact support@drofus.com to obtain your client_id and client_secret. Use these credentials to request an access token from the token endpoint.

Examples

Python

Postman

Basic HTTP

For testing and simple read-only access, dRofus API supports HTTP Basic Authentication. This method is straightforward to implement but is limited to read access and should not be used in production environments.

1. Generate an API key through the dRofus Power Query interface: https://help.drofus.com/en/English/Learning/power-query#PowerQuery-3.-Credentials%2FLogin .

2. Encode the API key in the format :api_key using Base64

3. Include the encoded string in the Authorization header

Bearer

API generally supports OAauth2 standard Bearer tokens. Registration process of OAuth2 client is currently manual, please reach out to support@drofus.com and we can provide needed information. Please send us the desired redirect_uri(s) (and if desired, post_logout_redirect_uri(s)).

For testing purpose, HTTP Basic authentication can also be used. However, it should be avoided for production applications. 

API-key

API supports reading data using "API-key". This access mode intended to be used by a person for reading ad-hoc data and/or recurring API-calls such as dashboards, PowerQuery (Excel, PoweBI), etc.

Keys can be generated as described here: Power Query#3.-Credentials/Login A generated key will reflect the logged in user and the project

Remarks using API-key

• It only supports reading operations

• An API-key is valid for a single project. A user may generate multiple API-keys for accessing different project. Generating API-Key twice for the same project will result in same key.

• API-keys belong to a single user and are confidential, thus should not be shared

• API-key does not intended to be used for machine-to-machine communication and should not be used as such

Technical description

One should send API-key with each HTTP request as standard Authorization header with Reference scheme

Authorization: Reference <API-key>

Note that many clients does not allow setting Authorization headers (for example Excel or pasting URL into browser's address bar), but will prompt for inputting username and password when server sends "Unauthorized" respond. Such prompt will result sending request with Authorization header with Basic scheme. So as a fallback, the application also accepting API-key encoded as Authorization header with Basic scheme, where username is a constant apikey and password is the API-key. The wire format will thus look like the following:

Authorization: Basic base64urlencode(apikey:<API-key>)

This is just an illustration, we recommend using Reference scheme whenever possible. Using API-key encoded in Basic scheme is unnecessary if clients have full control over request headers.

Providing database and projectId

All API endpoints should provide database and project number as part of the URL path, for example https://api-host/api/database/projectId/resources

Queries

We model our query-syntax on the OData standard, but currently only support a small subset of it. 

Full API documentation

The Api is described in a standard format, called Open API (formerly known as Swagger)

The basic general documentation for our API will be found under 'swagger/default/swagger.json'. But since our database is highly confiburable, a version with all database-specific files in the schemas are available under 'swagger/v1/swagger.json', but requires logon. 

RFC5988

Rfc5988 is an internet standard for navigating between pages in result-sets. Essentially it looks like this, and contains the full link for additonal data in the response headers: 

<http://localhost/api/database/01/rooms?$skip=1&$top=1>; rel=\"next\">

Examples

Examples of how to use the API:

Examples - Excel
Examples - PowerBI