Data Sources

  1. Documentation
  2. API Reference
  3. Data Sources

API Reference

Data Sources

The Data Source object

A Data Source object has the following properties:

  • id : string - The unique identifier of a data source
  • alias : string - The unique alias of a data source

Create a data source

Creates a new data source.

POST /api/v2/data-source

Arguments:

  • name - string : The name of the new data source
  • alias - string : The alias of the new data source (optional)
  • configUri - string : The connection URI of the data source

Response object:

  • A newly-created Data Source object with the following properties:
    • id - string : The unique identifier of the data source
    • name - string : The name of the data source
    • alias - string : The unique alias of the data source
    • type - string : The data source type
    • configUri - string : The connection URI of the data source
    • createdAt - timestamp : When the data source was created
    • updatedAt - timestamp : When the data source was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    "${JACKDB_API_URL}/data-source" \
    -d name=SomeDB&alias=some-db&configUri=postgresql://someuser:t0ps3cret@somedb.example.com:5432/some-db"

Example response:

{
  "id": "DKgU62P1dUlJfGTG",
  "name": "SomeDB",
  "alias": "some-db",
  "type": "postgresql",
  "configUri": "postgresql://someuser:t0ps3cret@somedb.example.com:5432/some-db?validateSsl=false&ssl=true",
  "createdAt": "2015-03-12T20:25:00.760Z",
  "updatedAt": "2015-03-12T20:25:00.760Z"
}

Delete a data source

Permanently deletes an existing data source.

DELETE /api/v2/data-source/:data-source

Arguments:

  • data-source - The identifier of the data source to be deleted

Response object:

This method returns an object with no properties.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0"

Example response:

{}

Delete all permissions granted on a data source

Permanently deletes all permissions granted on a data source.

DELETE /api/v2/data-source/:data-source/permission

Arguments:

  • data-source - The identifier of the data source

Response object:

  • An object with the following properties:
    • count - integer : the number of deleted permissions

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X DELETE \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/permission"

Example response:

{
  "count": 3
}

Execute data source command

Executes commands on an existing data source.

POST /api/v2/data-source/:data-source/execute

Available in JackDB Enterprise v6.0+

Arguments:

  • data-source - The identifier of the data source to be tested
  • commandTexts - string[] : List of commands to execute
  • retentionSeconds - number : Retention period for result in seconds (optional)

Response object:

  • A newly created API query object
  • If the connection attempt is successful, the endpoint returns an object with the following properties:
    • queryId - string : The unique identifier of the newly created API query object

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/test" \
    -H "Content-Type: application/json" \
    -d '{
        "commandTexts": [
          "SELECT 1 AS a",
          "SELECT x FROM generate_series(1, 10) x"
        ]
      }'

Example response:

{
  "queryId": "4f3da13d-df82-4328-b4ba-42d08cb28f53"
}

The list of commands will be executed in a single transaction, one after the other. Any result sets or outputs from each command will be aggregated before proceeding to the next command. If an error occurs, the entire transaction is rolled back.

List all permissions granted on a data source

Returns a list of all permissions granted on a data source.

GET /api/v2/data-source/:data-source/permission

Arguments:

  • data-source - The identifier of the data source

Response object:

  • An array of Permission objects
  • Each entry in the array is an object with the following properties:
    • id - string : The unique identifier of the permission
    • personId - string : The unique identifier of the person to whom this permission is granted
    • dataSourceId - string : The unique identifier of the data source onto which this permission is granted
    • startsAt - timestamp : When this permission is set to start
    • expiresAt - timestamp : When this permission is set to expire

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/permission"

Example response:

[
  {
    "id": "68939",
    "personId": "P0cKFCMIHoNaBFt7Y",
    "dataSourceId": "DUGC6IqGQ4DX00Lt0",
    "startsAt": "2015-03-12T23:47:14.120Z",
    "expiresAt": "2015-03-13T00:47:14.120Z"
  },
  {
    "id": "69303",
    "personId": "P0cKFCMIHoNaBFt7Y",
    "dataSourceId": "DUGC6IqGQ4DX00Lt0",
    "startsAt": "2015-03-12T23:47:14.120Z",
    "expiresAt": "2015-03-13T00:47:15.193Z"
  },
  {
    "id": "69603",
    "personId": "P3Fz69ORRudnQo5LE",
    "dataSourceId": "DUGC6IqGQ4DX00Lt0",
    "startsAt": "2015-03-12T23:47:14.120Z",
    "expiresAt": "2015-03-13T00:47:15.832Z"
  }
]

List all roles containing a data source

Returns a list of all roles containing a data source.

GET /api/v2/data-source/:data-source/role

Arguments:

  • data-source - The identifier of the data source

Response object:

  • An array of Role objects
  • Each entry in the array is an object with the following properties:
    • id - string : The unique identifier of the role
    • name - string : The name of the role
    • assignedAt - timestamp : When the data source was assigned to the role

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/role"

Example response:

[
  {
    "id": "RKm2x3dfX0b505iHy",
    "name": "HR",
    "assignedAt": "2014-07-27T15:01:59.901Z",
  },
  {
    "id": "RC98On0Dus9ZrskYH",
    "name": "Finance",
    "assignedAt": "2014-07-31T18:09:58.637Z",
  }
]

List all data sources

Returns a list of all data sources.

GET /api/v2/data-source

Arguments:

This method has no additional arguments.

Response object:

  • An array of Data Source objects
  • Each entry in the array is an object with the following properties:
    • id - string : The unique identifier of the data source
    • name - string : The name of the data source
    • alias - string : The unique alias of the data source
    • type - string : The data source type
    • configUri - string : The connection URI of the data source
    • createdAt - timestamp : When the data source was created
    • updatedAt - timestamp : When the data source was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source"

Example response:

[
  {
    "id": "DUGC6IqGQ4DX00Lt0",
    "name": "General Ledger",
    "alias": "gl-prod",
    "type": "postgresql",
    "configUri": "postgresql://gl@db.example.com:5432/gl",
    "createdAt": "2014-08-05T22:05:15.987Z",
    "updatedAt": "2014-09-04T18:23:32.777Z"
  },
  {
    "id": "DBnkfabo6VtpTaI7f",
    "name": "Stuff - Read Only",
    "alias": null,
    "type": "mysql",
    "configUri": "mysql://read_only@mydb.example.com:3306/stuff",
    "createdAt": "2014-08-29T19:55:42.666Z",
    "updatedAt": "2014-09-04T18:23:32.777Z"
  }
]

Note: The connection URI returned by this endpoint does not contain the password of the underlying database; only the database user, hostname, and port number are included.

Retrieve a data source

Retrieves the basic details of an existing data source.

GET /api/v2/data-source/:data-source

Arguments:

  • data-source - The identifier of the data source to be retrieved

Response object:

  • A Data Source object with the following properties:
    • id - string : The unique identifier of the data source
    • name - string : The name of the data source
    • alias - string : The unique alias of the data source
    • type - string : The data source type
    • configUri - string : The connection URI of the data source
    • createdAt - timestamp : When the data source was created
    • updatedAt - timestamp : When the data source was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0"

Example response:

{
  "id": "DUGC6IqGQ4DX00Lt0",
  "name": "General Ledger",
  "alias": "gl-prod",
  "type": "postgresql",
  "configUri": "postgresql://gl@db.example.com:5432/gl",
  "createdAt": "2014-08-05T22:05:15.987Z",
  "updatedAt": "2014-09-04T18:23:32.777Z"
}

Note: The connection URI returned by this endpoint does not contain the password of the underlying database; only the database user, hostname, and port number are included.

Retrieve a data source (detailed)

Retrieves the details of an existing data source.

GET /api/v2/data-source/:data-source/detail

Arguments:

  • data-source - The identifier of the data source to be retrieved

Response object:

  • A Data Source object with the following properties:
    • id - string : The unique identifier of the data source
    • name - string : The name of the data source
    • alias - string : The unique alias of the data source
    • type - string : The data source type
    • configUri - string : The connection URI of the data source
    • createdAt - timestamp : When the data source was created
    • updatedAt - timestamp : When the data source was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/detail"

Example response:

{
  "id": "DUGC6IqGQ4DX00Lt0",
  "name": "General Ledger",
  "alias": "gl-prod",
  "type": "postgresql",
  "configUri": "postgresql://gl:t0ps3cret@db.example.com:5432/gl",
  "createdAt": "2014-08-05T22:05:15.987Z",
  "updatedAt": "2014-09-04T18:23:32.777Z"
}

Note: The connection URI returned by this endpoint contains the password of the underlying database.

Test a data source

Test connecting to an existing data source.

POST /api/v2/data-source/:data-source/test

Arguments:

  • data-source - The identifier of the data source to be tested

Response object:

  • If the connection attempt is successful, the endpoint returns an object with the following properties:

    • success - boolean : Whether a connection to the data source could be established. (will be true for success responses)
    • version - object : The server version of the data source. This is provided for informational purposes and the exact format of this object may change in a future release. Currently it returns the major/minor/patch version of the remote database server as well as a text description of the server software and version.

  • If the connection attempt is not successful, the endpoint returns an object with the following properties:

    • success - boolean : Whether a connection to the data source could be established. (will be false for unsuccessful responses)
    • message - string : A description of the error encountered connecting to the data source.

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    "${JACKDB_API_URL}/data-source/DUGC6IqGQ4DX00Lt0/test"

Example responses:

{
  "success": true,
  "version": {
    "productName": "PostgreSQL",
    "productVersion": "9.6.2",
    "major": 9,
    "minor": 6,
    "patch": 2
  }
}

{
  "success": false,
  "message": "The connection timed out while trying to establish a connection. Please check that your data source is online and the proper firewall configuration has been setup."
}

Update a data source

Updates an existing data source.

POST /api/v2/data-source/:data-source

Arguments:

  • data-source - The identifier of the data source to be updated
  • name - string : The name of the data source
  • alias - string : The alias of the data source
  • configUri - string : The connection URI of the data source

Response object:

  • An updated Data Source object with the following properties:
    • id - string : The unique identifier of the data source
    • name - string : The name of the data source
    • alias - string : The unique alias of the data source
    • type - string : The data source type
    • configUri - string : The connection URI of the data source
    • createdAt - timestamp : When the data source was created
    • updatedAt - timestamp : When the data source was last updated

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    -X POST \
    "${JACKDB_API_URL}/data-source/DKgU62P1dUlJfGTG" \
    -d name=SomeDB&alias=some-db&configUri=postgresql://someuser:t0ps3cret@somedb.example.com:5432/some-db"

Example response:

{
  "id": "DKgU62P1dUlJfGTG",
  "name": "SomeDB",
  "alias": "some-db",
  "type": "postgresql",
  "configUri": "postgresql://someuser:t0ps3cret@somedb.example.com:5432/some-db?validateSsl=false&ssl=true",
  "createdAt": "2015-03-12T20:25:00.760Z",
  "updatedAt": "2015-03-12T20:25:00.760Z"
}

JackDB, Inc.

JackDB is a database technology company. Our platform offers a secure, collaborative environment for your organization's queries and data-driven insights.

If you have any questions about JackDB, or simply want to get in touch, contact us at hello@jackdb.com.

For enterprise sales inquiries, contact our sales team.

Product

Resources

Legal

© 2024 JackDB, Inc. All rights reserved.