RDM REST API
The RDM REST API lets you read the data and metadata from your RDM instance using REST interfaces.
Requests are made to the following base URL: https://rdm.<domain>/api/rest/
(or localhost:8060
for self-managed, on-premise deployments).
To get a list of all available endpoints and easily test them through Swagger UI, go to https://rdm.<domain>/swagger-ui/index.html
.
Authentication
Authentication is based on the Bearer scheme, which means that you need an access token obtained from Keycloak to send any requests. To configure authentication, set up a service account client in Keycloak and assign the necessary roles to it, then use it to retrieve the access token.
By default, these settings are enabled for the rdm-token-client in Keycloak.
|
The specific roles you assign depend on your RDM configuration. Typically, these roles are provided in the following properties (listed here with their default values):
-
ataccama.one.rdm.app-login-role=RDM
- The role required to access RDM and read other roles from Keycloak. The service account client must have this role assigned. -
ataccama.one.rdm.group-regex-filter=RDM.*
- Only the roles matching this regular expression are mapped to RDM so you can use them in RDM to define access to entities and attributes. -
ataccama.one.rdm.user-regex-filter=(^(?!service-account-).*)|service-account-.*rdm.*
- Only users matching this regular expression are loaded to RDM.If the default value is used, the property filters out all technical users not related to RDM (that is, whose name doesn’t contain the string
rdm
). Given that the username is derived from the client name, the client you want to use to access REST APIs must also containrdm
in its name.
For any custom Keycloak client you want to use with the RDM REST API (using OAuth 2.0), you need to enable the Service Accounts Enabled
option in Keycloak.
This creates the corresponding technical user (for example, for the rdm-token-client
, this would be service-account-rdm-token-client
).
The technical user must also pass the filter set in user-regex-filter in order for the roles and users to be mapped correctly between RDM and Keycloak.
|
For more detailed instructions about the configuration procedure, see API Requests Authentication.
Get application status
To get information about the application status, use the following request: GET /status
.
This call has no path or query string parameters and the response is a string, with one of the following values expected.
You can continue using the API if the response returned is SUCCESS
.
Application status | Description |
---|---|
STARTING |
The application is starting. |
WAITING_FOR_ACTION |
The application is waiting for some user action. You need to review and approve or reject a model proposal before proceeding. |
PROCESSING_MODEL |
The application is processing or updating the model. |
STOPPING_MODEL |
The application is stopping the model. |
FAILURE |
The application failed to start or deploy the model. |
SUCCESS |
The application is running and the model is successfully deployed. This is the only state in which the application is responding to requests. |
List data models
To get a list of all configured data models in the application, send a GET
request to the /models
endpoint.
Request | Description |
---|---|
|
Returns all available data models and the total number of models. |
|
Filters data models by their state.
Valid values: If no models are found for the state, the request returns an empty array ( |
For both requests, the response includes the number of available models (count
), as well as the following information about each model: the model name and identifier, the date and time when the model was uploaded, the model state.
{
"count": 2,
"data": [
{
"id": 2,
"name": "TEST",
"date": "2021-03-11T13:32:37.638Z",
"state": "ACTIVE"
},
{
"id": 1,
"name": "DEFAULT",
"date": "2021-03-11T13:31:06.094Z",
"state": "PROCESSED"
}
]
}
Get records with basic filtering
There are two requests you can use to retrieve table records with basic filtering applied.
Request | Description |
---|---|
|
Returns all records from the table ( |
|
Returns all records from the table ( The |
To narrow down the results, provide basic filters as query string parameters in the form of key-value pairs. If no filter is defined, both requests return all table records. You can also paginate results as needed.
Starting from 15.3.0, you can define how many records are returned in a single request.
See RDM Application Properties, properties ataccama.one.rdm.api.response.default-count and ataccama.one.rdm.api.response.max-count .
|
Query string parameter | Data type | Required | Description | ||||
---|---|---|---|---|---|---|---|
|
String |
No |
A basic filter consisting of one or more key-value pairs. You can add as many as needed. One key-value pair corresponds to one search condition, with the key referring to the column (attribute) name by which records are filtered and the value representing the search query. The search operator for each pair is the equals sign (
|
||||
_count |
Integer |
No |
Used for pagination. Defines the number of items listed on one page. |
||||
_offset |
Integer |
No |
Used for pagination. Defines how many items are skipped before returning results. |
Examples
The following examples show how to construct a request with basic filtering:
-
To read records from the
Branch
table and filter the results based on theBranch manager
andCity
attributes:GET /entity/branch?branch_manager=john%20smith&code=denver
-
To display records in the Edit mode from the
Country
table, with the record edit state set tochanged
. The page size is limited to 30, with no records skipped.GET /entity/country/edited?ac_edit_state=changed&_offset=0&_count=30
In both cases, the response contains the total number of records matching the search criteria (count
), regardless of any pagination options applied, and the filtered records (data
).
GET /entity/{entityName} response body
{
"count": 6,
"data": [
{
"generatedpk": "1",
"generatedgpk": "2",
"call_code": "+1",
"name_official": "United States of America",
"name_eng": "United States of America",
"flag": "us",
"name": "United States",
"id": "1",
"iso2": "US",
"iso3": "USA"
},
{
"generatedpk": "2",
"generatedgpk": "3",
"call_code": "+44",
"name_official": "United Kingdom of Great Britain and Northern Ireland",
"name_eng": "United Kingdom of Great Britain and Northern Ireland",
"flag": "uk",
"name": "United Kingdom",
"id": "2",
"iso2": "GB",
"iso3": "GBR"
},
{
"generatedpk": "3",
"generatedgpk": "4",
"call_code": "+33",
"name_official": "République française",
"name_eng": "French Republic",
"flag": "france",
"name": "France",
"id": "3",
"iso2": "FR",
"iso3": "FRA"
},
{
"generatedpk": "4",
"generatedgpk": "5",
"call_code": "+49",
"name_official": "Bundesrepublik Deutschland",
"name_eng": "Federal Republic of Germany",
"flag": "germany",
"name": "Germany",
"id": "4",
"iso2": "DE",
"iso3": "DEU"
},
{
"generatedpk": "5",
"generatedgpk": "6",
"call_code": "+358",
"name_official": "Suomen tasavalta",
"name_eng": "Republic of Finland",
"flag": "finland",
"name": "Finland",
"id": "5",
"iso2": "FI",
"iso3": "FIN"
},
{
"generatedpk": "6",
"generatedgpk": "7",
"call_code": "+1",
"name_official": "Canada",
"name_eng": "Canada",
"flag": "canada",
"name": "Canada",
"id": "6",
"iso2": "CA",
"iso3": "CAN"
}
]
}
Get records with advanced filtering
In addition to simple search queries, you can also use the RDM REST API for more complex filtering. If no filter is defined, both requests return all table records. You can also paginate results as needed.
Request | Description |
---|---|
|
Returns all records from the table ( |
|
Returns all records from the table ( The |
For both requests, the filter is provided in the request body in the JSON format and has the following structure:
-
filter
: Contains one required field,conditions
, and two optional ones,joinType
andordering
.-
joinType
: The logical operator between the conditions. Possible values: AND (default), OR. -
conditions
: An array of filtering options. Each condition must includecolumn
andvalue
fields.If no additional fields are provided, default values are used instead.
-
column
: The name of the column (attribute) by which records are filtered.The following system columns can be queried as well:
-
generatedpk
-
generatedgpk
-
username
-
ac_state
-
ac_edit_state
-
ac_date_from
-
ac_date_to
-
-
value
: The search query that is used to filter records.When filtering by date or datetime, use the ISO8601 format: 2022-02-20
,2022-02-09T00:00Z
, or2022-12-03T10:15:30+01:00
. -
operator
: The search operator. The default value iseq
(equal to). Supported options depend on the column data type.Possible values:
EQ
,NEQ
(not equal),LTE
(less than or equal),GTE
(greater than or equal),LT
(less than),GT
(greater than),CONTAINS
,EXCEPT
,BEGINS_WITH
,ENDS_WITH
,IS_EMPTY
,IS_NOT_EMPTY
. -
caseSensitive
: Used only for string columns. Set this totrue
if you want the filtering value to be case sensitive. Default value:false
.
-
-
ordering
: Defines how returned records are sorted. If not provided, records are ordered bygeneratedpk
(record identifier in the table) in ascending order.-
column
: The name of the column by which records are sorted. -
descending
: The order in which records are sorted. Default value:false
.
-
-
-
offset
: Used for pagination. Defines how many items are skipped before returning results. -
count
: Used for pagination. Defines the number of items listed on one page. -
modeSetup
: Used to define additional attributes for the viewing mode ifdataStage
is selected.-
<attribute>
: The following list contains the possible values for themodeSetup
fields and their descriptions.modeSetup attribute values: Click here to expand
Data viewing mode modeSetup attribute Data type Description Published (alternative: Confirmed), Edited, History, All History
businessDate
Datetime
Filters records with the given business date.
If null, all versions of records are returned in versions prior to 15.3.0. However, starting from 15.3.0, leaving this parameter empty returns only records that are currently valid (as defined in the business date columns for the table). For more details about record versioning, see Tables, section Business date columns, and Versioning Records in RDM.
To return only records that were valid at a particular date and time, provide that date in
businessDate
, for example:"modeSetup": { "businessDate": "2018-05-12T03:46:04Z", }
To return all records regardless of their validity, use
ignoreBusinessDates
instead.Published (alternative: Confirmed), Edited, History, All History
ignoreBusinessDates
Boolean
If set to
true
, all versions of records with business dates are returned, regardless of their validity.Example"modeSetup": { "ignoreBusinessDates": true }
Edited, All History
editState
String
Filters records based on their edit state. Possible values:
UNCHANGED
,NEW
,DELETED
,CHANGED
.Edited, All History
usernames
Array of strings
Filters records assigned to given users.
Edited
workflows
Array of strings
Filters records in the given workflow states.
Edited
valid
Boolean
Filters records based on whether they are marked as valid (
true
) or invalid (false
). If null, all records are returned.History
historyDate
Datetime
Filters records with the given date (historic snapshot).
All History
tags
Array of strings
Filters records with the given tags.
All History
from
andto
Datetime
Filters records existing in the period delimited by
from
andto
.
-
Advanced filter JSON structure: Click here to expand
{
"filter": {
"joinType": "or",
"conditions": [
{
"column": "name",
"operator": "eq",
"value": "france",
"caseSensitive": "true"
},
{
"column": "name",
"value": "United States"
}
],
"ordering": [
{
"column": "name",
"descending": "false"
}
]
},
"offset": "1",
"count": "5",
"modeSetup": {
"historyDate": "2022-02-09T00:00Z"
}
}
Examples
The following example shows how to query the Country
table in the History viewing mode using complex filters.
Here, we are looking for records where the country name matches the values 'France' or 'United States'.
Since the operator for the filtering values is not specified, the default option is used (eq
).
The case is ignored, and the results are ordered by the country name in ascending order. An additional filtering option is used to find records created before a particular date.
POST /entity/{entityName}/{dataStage} request body
{
"filter": {
"joinType": "or",
"conditions": [
{
"column": "name",
"value": "france"
},
{
"column": "name",
"value": "United States"
}
],
"ordering": [
{
"column": "name",
"descending": "false"
}
]
},
"offset": "1",
"count": "5",
"modeSetup": {
"historyDate": "2022-02-09T00:00Z"
}
}
The response contains the total number of records matching the search criteria (count
), regardless of any pagination options applied, and the filtered records (data
).
The same applies for the request POST /entity/{entityName}
.
In the previous request, we defined the paging so that the first result is skipped and a maximum of 5 records are returned.
POST /entity/{entityName}/{dataStage} response body
{
"count": 2,
"data": [
{
"generatedpk": "1",
"generatedgpk": "2",
"ac_date_from": "2021-03-11T13:37:26.000Z",
"ac_date_to": null,
"username": "admin",
"call_code": "+1",
"name_official": "United States of America",
"name_eng": "United States of America",
"flag": "us",
"name": "United States",
"id": "1",
"iso2": "US",
"iso3": "USA"
}
]
}
Get record link
You can use the REST API to generate an encoded link to a particular RDM record.
To do this, use the request GET /link
and provide the required query string parameters.
Query string parameter | Data type | Required | Description |
---|---|---|---|
entityName |
String |
Yes |
The name of the table where the record is located. |
generatedpk |
Integer |
Yes |
The generated primary key, that is, the record identifier.
Corresponds to the |
mode |
String |
No |
The view mode in which the record is displayed.
Valid values: For more details about viewing modes, see Data Viewing Modes. |
hcn |
Integer |
No |
The history change number of the record.
The parameter has higher priority over |
The response returns a string you can use to view the record. Keep in mind that users still need to have the correct viewing permissions for the entity and be logged in to RDM to access the record.
GET https://rdm.<domain>/api/rest/link?generatedpk=2&entityname=product
rdm.<domain>/mailLink.html#encoded:4616471645162637D3B7224716263722A3B5B7224656471696C645162622A3B722D6F6465622A3B722D6F64656
22A32214C4C4F584943545F4259522C2228636E622A313D7C222964622A3B55303D5C222471626C656E416D65622A3220727F64657364722D7D7D5D7
Once you open the link in your browser, the record is displayed in the RDM web application as follows:
![Record detail in RDM web application](_images/rdm-rest-api-get-record-link.png)
Was this page useful?