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
}

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