ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
latest (15.3.0) 15.2.0 15.1.x 14.5.x 13.9.x 13.8.x 13.7.x 13.6.x 13.5.0 13.4.x 13.3.x 13.2.x
User Community Service Desk Downloads
If you can't find the product or version you're looking for, visit support.ataccama.com/downloads

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 contain rdm 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

GET /models

Returns all available data models and the total number of models.

GET /models?state=active

Filters data models by their state. Valid values: scheduled, approved, active, processed.

If no models are found for the state, the request returns an empty array (data).

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.

GET /models response body
{
    "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

GET /entity/{entityName}

Returns all records from the table (entityName) matching the applied search criteria.

GET /entity/{entityName}/{dataStage}

Returns all records from the table (entityName) matching the applied search criteria in the specified data viewing mode (dataStage).

The dataStage parameter allows the following values: EDITED, PUBLISHED (alternative: CONFIRMED), HISTORY, ALL_HISTORY, INPUTS, CART. For more details about viewing modes, see Data Viewing Modes.

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

key=value

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 (=) and the logical operator used to join multiple conditions is AND.

The following system columns can be queried as well:

  • generatedpk

  • generatedgpk

  • username

  • ac_state

  • ac_edit_state

  • ac_date_from

  • ac_date_to
When filtering by date or datetime, use the ISO8601 format: 2022-02-20, 2022-02-09T00:00Z, or 2022-12-03T10:15:30+01:00.

_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 the Branch manager and City 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 to changed. 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

POST /entity/{entityName}

Returns all records from the table (entityName) matching the applied search criteria. Allows using advanced filtering options.

POST /entity/{entityName}/{dataStage}

Returns all records from the table (entityName) matching the applied search criteria in the specified data viewing mode (dataStage). Allows using advanced filtering options.

The dataStage parameter allows the following values: EDITED, PUBLISHED (alternative: CONFIRMED), HISTORY, ALL_HISTORY, IMPORT, INPUTS, CART. For more details about viewing modes, see Data Viewing Modes.

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 and ordering.

    • joinType: The logical operator between the conditions. Possible values: AND (default), OR.

    • conditions: An array of filtering options. Each condition must include column and value 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, or 2022-12-03T10:15:30+01:00.

      • operator: The search operator. The default value is eq (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 to true 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 by generatedpk (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 if dataStage is selected.

    • <attribute>: The following list contains the possible values for the modeSetup 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 and to

      Datetime

      Filters records existing in the period delimited by from and to.
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"
        }
    ]
}

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 ID column in the table.

mode

String

No

The view mode in which the record is displayed. Valid values: PUBLISHED (alternative: CONFIRMED), EDIT, HISTORY, ALL_HISTORY, CART, INPUTS.

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 mode; if the hcn parameter is defined, the mode is automatically set to ALL_HISTORY.

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 /link request example
GET https://rdm.<domain>/api/rest/link?generatedpk=2&entityname=product
GET /link response body
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

Was this page useful?