Skip to content

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