Data Dictionary HTTP API

Audience: Data Owners

Content Summary: The Data Dictionary API allows users to interact programmatically with the Data Dictionary for their data sources.

This page outlines request parameters for viewing the data types in saved Data Dictionaries, deleting a Data Dictionary, creating a Data Dictionary, and updating a Data Dictionary for a data source.

Get Dictionary Types

Get a list of all the distinct data types from the saved dictionaries.

Method	Path	Successful Status Code
GET	`/dictionary/types`	200

Request Parameters

query (string): optional query string used to filter results

Example Request:

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

Response

The response is a list of data type strings.

Example Response:

[
  "timestamp with time zone",
  "timestamptz",
  "date",
  "int",
  "varchar(400)",
  "double precision",
  "money",
  "character varying",
  "decimal",
  "timestamp",
  "boolean",
  "integer",
  "json",
  "varchar",
  "numeric",
  "text"
]

Get Data Source Dictionary

Get the dictionary for the specified data source.

Method	Path	Successful Status Code
GET	`/dictionary/{dataSourceId}`	200

Request Path Parameters

dataSourceId (integer): ID of the data source that is being queried.
- Example: 1

Example Request:

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

Response

This endpoint returns a Dictionary Object.

Example Response:

{
  "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"
}

Delete Data Source Dictionary

Delete the dictionary for the specified data source.

Method	Path	Successful Status Code
DELETE	`/dictionary/{dataSourceId}`	200

Request Path Parameters

dataSourceId (integer): ID of the data source that is being queried.
- Example: 1

Example Request:

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

Response

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

Create Data Source Dictionary

Create the dictionary for the specified data source.

Method	Path	Successful Status Code
POST	`/dictionary/{dataSourceId}`	200

Request Path Parameters

dataSourceId (integer): ID of the data source that is being queried.
- Example: 1

Request Parameters

metadata (object): The dictionary metadata. See metadata under Dictionary Object for more details.

Example Request Payload:

{
  "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"
    }
  ]
}

Example Request:

curl \
    --request POST \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    --data @example-payload.json \
    https://demo.immuta.com/dictionary/1

Response

This endpoint returns a Dictionary Object.

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

Example Response:

{
  "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"
}

Update Data Source Dictionary

The update data source dictionary endpoint will update the dictionary for the specified data source.

Method	Path	Successful Status Code
PUT	`/dictionary/{dataSourceId}`	200

Request Path Parameters

dataSourceId (integer): ID of the data source that is being queried.
- Example: 1

Request Parameters

metadata (object): The dictionary metadata. See metadata under Dictionary Object for more details.

Example Request Payload:

{
  "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"
    }
  ]
}

Example Request:

curl \
    --request POST \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    --data @example-payload.json \
    https://demo.immuta.com/dictionary/1

Response

This endpoint returns a Dictionary Object.

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

Example Response:

{
  "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"
}

Dictionary Object

createdAt (timestamp): When the object was created.
- Example: 2018-03-21T10:52:30.535Z
dataSource (integer): ID of the data source this dictionary is associated with.
- Example: 1
id (integer): ID of the dictionary object.
- Example: 1
metadata ([]object): Metadata for the individual fields in the dictionary.
- Fields:
  - name (string): Name of the dictionary field.
  - dataType (string): Type of the data as exposed in Immuta.
  - remoteType (string): Type of the data in the remote database.
- Example:
  
  [ { "name": "notificationType", "dataType": "text", "remoteType": "varchar(255)" }, { "name": "actionBy", "dataType": "text", "remoteType": "integer" } ]
types ([]string): List of all types this dictionary contains
- Example: ["text", "integer", "json", "timestamp with time zone"]
updatedAt (timestamp): When the object was last updated.
- Example: 2018-03-21T10:52:30.535Z