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

Manage the dictionary for a data source.
Search dictionaries.
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

EndpointQuery ParametersPayload ParametersResponse Parameters

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

EndpointQuery ParametersPayload ParametersResponse Parameters

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

EndpointQuery ParametersResponse Parameters

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

EndpointQuery ParametersResponse Parameters

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

EndpointQuery ParametersResponse Parameters

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.