Skip to content

You are viewing documentation for Immuta version 2024.1.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

Data Dictionary API Reference Guide

The data dictionary API allows you to manage the data dictionary for your data sources.

Note

Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.

Data dictionary workflow

  1. Manage the dictionary for a data source.
  2. Search dictionaries.
  3. Delete a dictionary for a data source.

Manage data dictionaries

Method Path Purpose
POST /dictionary/{dataSourceId} Create the dictionary for the specified data source.
PUT /dictionary/{dataSourceId} Update the data dictionary for the specified data source.

Create a data dictionary

Endpoint

Method Path Purpose
POST /dictionary/{dataSourceId} Create the dictionary for the specified data source.

Query Parameters

Attribute Description Required
dataSourceId integer The ID of the data source that will contain the data dictionary. Yes
body array[object] Data dictionary metadata, including column names, data types, description and tags. Yes

Payload Parameters

Attribute Description Required
name string The name of the column. Yes
dataType string The type of data in the column. Yes
remoteType string The type of data in the remote column. Yes

Response Parameters

Attribute Description
createdAt timestamp When the object was created.
dataSource integer The ID of the data source the dictionary is associated with.
id integer The ID of the dictionary object.
metadata array[string] Metadata for the individual fields in the dictionary, including name, dataType, and remoteType.
types array[string] A list of all data types the dictionary contains, such as text, integer, json, or timestamp with time zone.

Request example

The following request creates a data dictionary (saved in example-payload.json) for the data source with ID 1.

curl \
    --request POST \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    --data @example-payload.json \
    https://demo.immuta.com/dictionary/1
Payload example
{
  "metadata": [
    {
      "name": "notificationType",
      "dataType": "text",
      "remoteType": "text"
    },
    {
      "name": "actionBy",
      "dataType": "text",
      "remoteType": "integer"
    },
    {
      "name": "targetUser",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "metadata",
      "dataType": "json",
      "remoteType": "json"
    },
    {
      "name": "id",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "notifyInitiator",
      "dataType": "text",
      "remoteType": "boolean"
    },
    {
      "name": "eventTime",
      "dataType": "timestamp with time zone",
      "remoteType": "timestamp with time zone"
    }
  ]
}

Response example

{
  "createdAt": "2018-03-21T10:52:30.535Z",
  "dataSource": 1,
  "id": 1,
  "metadata": [
    {
      "name": "notificationType",
      "dataType": "text",
      "remoteType": "text"
    },
    {
      "name": "actionBy",
      "dataType": "text",
      "remoteType": "integer"
    },
    {
      "name": "targetUser",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "metadata",
      "dataType": "json",
      "remoteType": "json"
    },
    {
      "name": "id",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "notifyInitiator",
      "dataType": "text",
      "remoteType": "boolean"
    },
    {
      "name": "eventTime",
      "dataType": "timestamp with time zone",
      "remoteType": "timestamp with time zone"
    }
  ],
  "types": [
    "text",
    "integer",
    "json",
    "timestamp with time zone"
  ],
  "updatedAt": "2018-03-21T12:18:25.531Z"
}

Other status codes returned include:

Status Code Message
400 Bad request: (detailed reason).
401 A valid Authorization token must be provided.
403 User must have one of the following roles to delete dictionary: owner,expert.
404 Data source not found.

Update a data dictionary

Endpoint

Method Path Purpose
PUT /dictionary/{dataSourceId} Update the dictionary for the specified data source.

Query Parameters

Attribute Description Required
dataSourceId integer The ID of the data source that will contain the data dictionary. Yes
body array[object] Data dictionary metadata, including column names, data types, description and tags. Yes
Attribute Description Required
name string The name of the column. Yes
dataType string The type of data in the column. Yes
remoteType string The type of data in the remote column. Yes

Response Parameters

Attribute Description
createdAt timestamp When the object was created.
dataSource integer The ID of the data source the dictionary is associated with.
id integer The ID of the dictionary object.
metadata array[string] Metadata for the individual fields in the dictionary, including name, dataType, and remoteType.
types array[string] A list of all data types the dictionary contains, such as text, integer, json, or timestamp with time zone.

Request example

The request below updates the data dictionary for the data source with the ID 1.

curl \
    --request PUT \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    --data @example-payload.json \
    https://demo.immuta.com/dictionary/1
Payload example
{
  "metadata": [
    {
      "name": "notificationType",
      "dataType": "text",
      "remoteType": "text"
    },
    {
      "name": "actionBy",
      "dataType": "text",
      "remoteType": "integer"
    },
    {
      "name": "targetUser",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "metadata",
      "dataType": "json",
      "remoteType": "json"
    },
    {
      "name": "id",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "notifyInitiator",
      "dataType": "text",
      "remoteType": "boolean"
    },
    {
      "name": "eventTime",
      "dataType": "timestamp with time zone",
      "remoteType": "timestamp with time zone"
    }
  ]
}

Response example

{
  "createdAt": "2018-03-21T10:52:30.535Z",
  "dataSource": 1,
  "id": 1,
  "metadata": [
    {
      "name": "notificationType",
      "dataType": "text",
      "remoteType": "text"
    },
    {
      "name": "actionBy",
      "dataType": "text",
      "remoteType": "integer"
    },
    {
      "name": "targetUser",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "metadata",
      "dataType": "json",
      "remoteType": "json"
    },
    {
      "name": "id",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "notifyInitiator",
      "dataType": "text",
      "remoteType": "boolean"
    },
    {
      "name": "eventTime",
      "dataType": "timestamp with time zone",
      "remoteType": "timestamp with time zone"
    }
  ],
  "types": [
    "text",
    "integer",
    "json",
    "timestamp with time zone"
  ],
  "updatedAt": "2018-03-21T12:18:25.531Z"
}

Other status codes returned include

Status Code Message
400 Bad request: (detailed reason).
401 A valid Authorization token must be provided.
403 User must have one of the following roles to delete dictionary: owner,expert.
404 Data source not found.

Search data dictionaries

Method Path Purpose
GET /dictionary/{dataSourceId} Get the dictionary for the specified data source.
GET /dictionary/columns Search across all dictionary columns.

Get the dictionary for a specified data source

Endpoint

Method Path Purpose
GET /dictionary/{dataSourceId} Get the dictionary for the specified data source.

Query Parameters

Attribute Description Required
dataSourceId integer The ID of the data source that contains the data dictionary. Yes

Response Parameters

Attribute Description
createdAt timestamp When the object was created.
dataSource integer The ID of the data source the dictionary is associated with.
id integer The ID of the dictionary object.
metadata array[string] Metadata for the individual fields in the dictionary, including name, dataType, and remoteType.
types array[string] A list of all data types the dictionary contains, such as text, integer, json, or timestamp with time zone.

Request example

The request below gets the data dictionary for the data source with the ID 1.

curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    https://demo.immuta.com/dictionary/1

Response example

{
  "createdAt": "2018-03-21T10:52:30.535Z",
  "dataSource": 1,
  "id": 1,
  "metadata": [
    {
      "name": "notificationType",
      "dataType": "text",
      "remoteType": "text"
    },
    {
      "name": "actionBy",
      "dataType": "text",
      "remoteType": "integer"
    },
    {
      "name": "targetUser",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "metadata",
      "dataType": "json",
      "remoteType": "json"
    },
    {
      "name": "id",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "notifyInitiator",
      "dataType": "text",
      "remoteType": "boolean"
    },
    {
      "name": "eventTime",
      "dataType": "timestamp with time zone",
      "remoteType": "timestamp with time zone"
    }
  ],
  "types": [
    "text",
    "integer",
    "json",
    "timestamp with time zone"
  ],
  "updatedAt": "2018-03-21T12:18:25.531Z"
}

Search across all dictionary columns

Endpoint

Method Path Purpose
GET /dictionary/columns Search across all dictionary columns.

Query Parameters

Attribute Description Required
searchText string A string used to filter returned columns. The query is executed with a wildcard prefix and suffix. No
limit integer The maximum number of search results that will be returned. Default is 10. No

Response Parameters

Attribute Description
columnName string The name of the column.

Request example

The following request searches for columns in all dictionaries that contain the text address in their name, with a limit of 10 results.

curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    https://demo.immuta.com/dictionary/columns?searchText=address&limit=10

Response example

[
  "address_city",
  "address_state",
  "address_street"
]

Delete a data dictionary

Endpoint

Method Path Purpose
DELETE /dictionary/{dataSourceId} Delete the data dictionary for the specified data source.

Query Parameters

Attribute Description Required
dataSourceId integer The ID of the data source. Yes

Response Parameters

None.

Request example

The request below deletes the data dictionary for the data source with ID 1.

curl \
    --request DELETE \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    https://demo.immuta.com/dictionary/1

Response example

This endpoint returns {} on success.

Other status codes returned include

Status Code Message
401 A valid Authorization token must be provided.
403 User must have one of the following roles to delete dictionary: owner,expert.
404 Data source not found.