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.
| URL | Swagger Gui | Swagger JSON | Note |
|---|---|---|---|
https://api-no.drofus.com | API documentation and test it in web GUI | Open API Specification | use for db2.nosyko.no projects |
https://api-eu.drofus.com | API documentation and test it in web GUI | Open API Specification | |
| https://api-ca.drofus.com | API documentation and test it in web GUI | Open API Specification | |
| https://api-us.drofus.com | API documentation and test it in web GUI | Open API Specification | |
| https://api-au.drofus.com/ | API documentation and test it in web GUI | Open API Specification |
Authentication
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. It does not intended to be used for machine-to-machine communication
Keys can be generated as described here: Power Query#3.-Credentials/Login
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
Technical description
One should send API-key with each HTTP request as standard Authorization header with Reference scheme
Authorization: Reference <API-key>
Whenever possible we recommend using Reference scheme whenever possible. 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.
Authorization: Basic base64urlencode(apikey:<API-key>)
Note that many clients (for example Excel or browsers) will prompt users for inputting username and password if a request is sent without Authorization header and will result re-sending request with Authorization header with Basic scheme
Providing database and projectId
All API endpoints should provide database and project id as part of the url. E.g. https://api-xyz.com/database/projectId/api/rooms
[Deprecated] Providing database and projectId in "Basic auth"
When using HTTP Authorization header Basic scheme, it is possible to provide the following parameters for scheme's "username", separated by slash. This is deprecated in favour of path. For example:
HTTP GET /api/rooms
Authorization: Basic base64(my-database/01/my-username/en:mypassword)
Possible parameters
| Name | Meaning |
|---|---|
| db-name | The database-name as you would enter in dRofus Client |
| project-id | Id of project. Usually '01'. This is optional only if database only contains one project |
| user-name | The name you log on with in dRofus client |
| language | The language you want to see data in. Optional, and default is the language configured for the database |
Queries
We model our query-syntax on the OData standard, but currently only support a small subset of it.
| Argument | Description | Sample | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| $select | A comma-separated list of columns to return. 'id' will always be returned | $select=name,architect_no | ||||||||||||||||||
| $orderby | A comma-separated list of columns to sort by. Sorting direction can be specified using asc or desc. Default is asc. If no orderby is specified, the result is sorted by id | $orderby=name,architect_no desc, | ||||||||||||||||||
| $filter | Used to restrict which rows are returned. A column can have a criteria to filter by. The value for filter can be quoted to handle embedded spaces and strings. Currently only 'and' can be used to combine multiple filters. Operators:
| $filter=created gt '2019-1-1' $filter=name in ('kitchen', 'office') $filter=id in (1001, 1003, 1005) $filter=contains(name,'kitch') | ||||||||||||||||||
| $top | Max number of rows to return. Default is 10000. If more data is available than is returned, the result will contain a RFC5988 header value | $top=123 | ||||||||||||||||||
| $skip | How many rows to skip on result-set. Default is 0. Can be combined with $top to implement paging | $skip=100 |
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: