Skip to main content

RDD Integrations API

The RDD Integrations API was built to enable more scalably managing RDD integrations using standard CRUD functions. Below you can find a list of all available methods to create, retrieve, update and delete RDD Integrations allowing you to manage data sources you wish to scan for data classification.

API Conventions​

All URLs listed in the documentation should have the same base URL that precedes each route. This consists of your organization's DataGrail URL along with the API version:

https://${yoursubdomain.datagrail.io}/api/v2

Authorization​

In order to use this API, you must first set up an RDD agent. An agent's associated API key is required to authenticate and authorize requests to this API. The API key will be required as a bearer token in the Authorization header.

Create an Integration​

POST RDD integration details for a system to be scanned using an authenticated agent. If successful, the newly created integration's ID will be returned. Note that names are required to be globally unique. Here, any unique identifier like a hostname, ARN, or service name that is easily associated with a unique system can be used.

Endpoint​

POST /api/v2/data_discovery/integrations

Headers​

ParameterDescription
Authorizationstring (required)
Your bearer token.

Body Parameters​

ParameterDescription
namestring (required)
The integration name. Must be unique.
connector_typeenum(ConnectorType) (required)
The type of connector.
credentials_locationstring (required)
The vault ID or key storing integration credentials.
regionstring (optional)
The region where the system is located.
locationstring (optional)
The country where the system is located.
business_processstring (optional)
The associated business process.

ConnectorType​

EnumDescription
athenaConnect to AWS Athena
mongo_dbConnect a MongoDB database
mysqlConnect a MySQL database
postgresConnect a PostgreSQL database.
redshiftConnect a Redshift data warehouse
snowflakeConnect a Snowflake data warehouse

Example Request​

curl -XPOST "https://${yoursubdomain.datagrail.io}/api/v2/data_discovery/integrations" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
      "name": "prod-mysql-001",
      "connector_type": "mysql",
      "credentials_location": "arn:aws:secretsmanager:us-west-2:1234567890:secret:secret-name"
  }'

Example Response - 200 OK​

{
 "id": "133d27c7-7e88-4488-85f3-10e98e2e8cb3"
}

List all Integrations​

GET a list of integrations for an authenticated agent.

Endpoint​

GET /api/v2/data_discovery/integrations

Headers​

ParameterDescription
Authorizationstring (required)
Your bearer token.

Example Request​

curl -XGET "https://${yoursubdomain.datagrail.io}/api/v2/data_discovery/integrations" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>"

Example Response (200 OK)​

{
  "integrations": [
    {
      "id": "a99f4d71-6fb3-4e38-b5df-a175990a98b4",
      "connector_type": "mysql",
      "name": "mysql1",
      "credentials_location": "arn:blah:blah",
      "region": "us-west-2",
      "business_process": null,
      "location": null,
      "status": "connected",
      "created_at": "2024-01-01T00:53:54.316Z",
      "updated_at": "2024-01-01T00:53:55.028Z"
    },
    {
      "id": "133d27c7-7e88-4488-85f3-10e98e2e8cb3",
      "connector_type": "postgres",
      "name": "postgres2",
      "credentials_location": "arn:blah:blah",
      "region": "us-west-2",
      "business_process": null,
      "location": null,
      "status": "not_connected",
      "created_at": "2024-01-01T00:53:55.123Z",
      "updated_at": "2024-01-01T00:53:55.612Z"
    }
  ],
  "total": 2
}

Get an Integration​

GET an RDD integration for an authenticated agent.

Endpoint​

GET /api/v2/data_discovery/integrations/:id

Headers​

ParameterDescription
Authorizationstring (required)
Your bearer token.

Path Parameters​

ParameterDescription
idUUID (required)
The integration ID

Example Request​

curl -XGET "https://${yoursubdomain.datagrail.io}/api/v2/data_discovery/integrations/133d27c7-7e88-4488-85f3-10e98e2e8cb3" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>"

Example Response (200 OK)​

{
  "id": "133d27c7-7e88-4488-85f3-10e98e2e8cb3",
  "connector_type": "postgres",
  "name": "postgres2",
  "credentials_location": "arn:blah:blah",
  "region": "us-west-2",
  "business_process": null,
  "location": null,
  "status": "not_connected",
  "created_at": "2024-01-01T00:53:55.123Z",
  "updated_at": "2024-01-01T00:53:55.612Z"
}

Update an Integration​

UPDATE RDD integration details for a system to be scanned using an authenticated agent. Note that names are required to be globally unique. Here, any unique identifier like a hostname, ARN, or service name that is easily associated with a unique system can be used.

Endpoint​

PUT /api/v2/data_discovery/integrations/:id

Headers​

ParameterDescription
Authorizationstring (required)
Your bearer token.

Path Parameters​

ParameterDescription
idUUID (required)
The integration ID

Body Parameters​

ParameterDescription
namestring (required)
The integration name. Must be unique.
connector_typestring (required)
The type of connector.
credentials_locationenum(ConnectorType) (required)
The vault ID or key storing integration credentials.
regionstring (optional)
The region where the system is located.
locationstring (optional)
The country where the system is located.
business_processstring (optional)
The associated business process.

Example Request​

curl -XPUT "https://${yoursubdomain.datagrail.io}/api/v2/data_discovery/integrations/133d27c7-7e88-4488-85f3-10e98e2e8cb3" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
      "name": "prod-postgres-001",
      "connector_type": "postgres",
      "credentials_location": "arn:aws:secretsmanager:us-west-2:1234567890:secret:secret-name"
  }'

Example Response (200 OK)​

{}

Delete an Integration​

DELETE an RDD integration for an authenticated agent

Endpoint​

DELETE /api/v2/data_discovery/integrations/:id

Headers​

ParameterDescription
Authorizationstring (required)
Your bearer token.

Path Parameters​

ParameterDescription
idUUID (required)
The integration ID

Example Request​

curl -XDELETE "https://${yoursubdomain.datagrail.io}/api/v2/data_discovery/integrations/133d27c7-7e88-4488-85f3-10e98e2e8cb3" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>"

Example Response (200 OK)​

{}

Error Codes​

This API uses the following error codes:

CodeDescription
401Unauthorized -- Your API key is incorrect or invalid.
404Not Found -- The integration could not be found. Confirm the route or integration id are correct.
422Unprocessable Entity -- The request body cannot be processed. Ensure that you're passing the correct parameters.
500Internal Server Error -- An internal and unexpected error condition occurred.

 

Need help?
If you have any questions, please reach out to your dedicated CSM or contact us at support@datagrail.io.

Disclaimer: The information contained in this message does not constitute as legal advice. We would advise seeking professional counsel before acting on or interpreting any material.