このドキュメントは、dRofus REST API を使用して、特定のデータベースからデータを取得するための参考資料を示すものです。データベース管理 REST API については、こちらを参照してください： 管理システム REST API
このAPIは、APIを記述したオープン API 仕様を提供しています。また、このAPIを探索し、ブラウザ上で試すことができる
インタラクティブなGUIも用意しています。データベース/プロジェクト特有のプロパティを取得する方法を公開し、
文書化しているため、文書を参照するにはログインする必要があります。下記の認証を参照してください。
フィードバックを提供
APIをどのような用途でお使いになりたいか、ご遠慮なくお問い合わせください。
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 | use for db2.nosyko.no projects | ||
https://api-eu.drofus.com | |||
https://api-ca.drofus.com | |||
https://api-us.drofus.com | |||
https://api-au.drofus.com/ |
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.
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.
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 |
完全なAPIドキュメント
APIは、Open API (以前はSwaggerとして知られていました) と呼ばれる標準フォーマットで記述されています。
APIの基本的な一般ドキュメントは、'swagger/default/swagger.json'にあります。
しかし、我々のデータベースは高度な設定が可能であるため、データベース固有のファイルをすべてスキーマに含む
バージョンは、'swagger/v1/swagger.json'にありますが、ログオンが必要です。
RFC5988
Rfc5988は、結果セットのページ間をナビゲートするためのインターネット標準です。基本的にはこのようなもので、
レスポンスヘッダに追加データの完全なリンクが含まれています：
<http://localhost/api/database/01/rooms?$skip=1&$top=1>; rel=\"next\">
使用例
APIの使用例です：