Snippets

The Snippet object

A Snippet object has the following properties:

• id : string - The unique identifier of a snippet

The Snippet Version object

A Snippet Version object has the following properties:

• id : string - The unique identifier of a snippet version

Create a snippet

Creates a new snippet.

Arguments:

• name - string : The name for the inital version of the snippet
• description - string : The description for the inital version of the snippet
• text - string : The text for the inital version of the snippet
• createdByPersonId - string : The optional created by person for the inital version of the snippet
• isLocked - boolean : Whether the snippet is locked
• publicAccessLevel - string : The public access level of this snippet for non-owners, either ’none’, ‘read_only’, ‘read_write’, or ‘manage’
• owner - string : The type of owner for the snippet, either ’none’, ‘role’, or ‘person’
• ownerPersonId - string : The optional owner person of the snippet or null (must be populated for owner type ‘person’)
• ownerRoleId - string : The optional owner role of the snippet or null (must be populated for owner type ‘role’)

Response object:

• A newly-created Snippet object with the following properties:
  • id - string : The unique identifier of the snippet
  • activeVersion - object : The active version of this snippet
    • id - string : The unique identifier of the active snippet version
    • name - string : The name of the active snippet version
    • description - string : The description of the active snippet version
    • text - string : The text of the active snippet version
  • isLocked - boolean : Whether the snippet is locked
  • publicAccessLevel - string : The public access level of this snippet for non-owners, either ’none’, ‘read_only’, ‘read_write’, or ‘manage’
  • ownerPerson - object : The person that owns this snippet or null
    • id - string : The unique identifier of the person
    • username - string : The username the person
    • email - string : The email of the person
    • name - string : The display of the person
  • ownerRole - object : The role that owns this snippet or null
    • id - string : The unique identifier of the person
    • name - string : The display of the person
  • createdAt - timestamp : When the snippet was created
  • updatedAt - timestamp : When the snippet 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}/snippet" \
    -d "name=sample&description=A sample query&text=SELECT 1&publicAccessLevel=none&owner=person&ownerPersonId=PkNJRdbtfjFsL6CaC"

Example response:

{
  "id": "ScRthIsjOBol2ULt",
  "activeVersion": {
    "id": "243f5c00-cbc8-4857-b1c6-e117903ec854",
    "name": "sample",
    "description": "A sample query",
    "text": "SELECT 1"
  },
  "isLocked": false,
  "publicAccessLevel": "none",
  "ownerPerson": {
    "id": "PkNJRdbtfjFsL6CaC",
    "username": "abrewer",
    "email": "angelique.brewer@example.com",
    "name": "Angelique Brewer"
  },
  "ownerRole": null,
  "createdAt": "2019-08-14T16:16:10.448Z",
  "updatedAt": "2019-08-14T16:16:10.448Z"
}

Create snippet version

Create a new version of an existing snippet.

Arguments:

• snippet - string : The identifier of the snippet
• name - string : The name for the inital version of the snippet
• description - string : The description for the inital version of the snippet
• text - string : The text for the inital version of the snippet
• createdByPersonId - string : The optional created by person for the version of the snippet

Response object:

• A newly-created Snippet Version object with the following properties:
  • id - string : The identifier of the snippet version
  • snippetId - string : The identifier of the snippet
  • name - string : The name of the snippet version
  • description - string : The description of the snippet version
  • text - string : The text of the snippet version
  • createdAt - timestamp : When the snippet version was created
  • createdBy - object : The person that created this snippet version or null
    • id - string : The unique identifier of the person
    • username - string : The username the person
    • email - string : The email of the person
    • name - string : The display of the person

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}/snippet/SQxfo8qICrZG1ZT7/version" \
    -d "name=sample&description=A sample query&text=SELECT 2&createdByPersonId=PkNJRdbtfjFsL6CaC"

Example response:

{
  "id": "4170855d-802e-4347-8d8d-1183ef9a05c5",
  "snippetId": "SQxfo8qICrZG1ZT7",
  "name": "sample",
  "description": "A sample query",
  "text": "SELECT 2",
  "createdAt": "2019-08-14T20:37:30.795Z",
  "createdBy": {
    "id": "PkNJRdbtfjFsL6CaC",
    "username": "abrewer",
    "email": "angelique.brewer@example.com",
    "name": "Angelique Brewer"
  }
}

Delete a snippet

Deletes an existing snippet.

Arguments:

• snippet - string : The identifier of the snippet 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}/snippet/ScRthIsjOBol2ULt"

Example response:

{}

List snippet versions

List all versions of an existing snippet.

Arguments:

• snippet - string : The identifier of the snippet

Response object:

• An array of Snippet Version objects
• Each entry in the array is an object with the following properties:
  • id - string : The identifier of the snippet version
  • snippetId - string : The identifier of the snippet
  • name - string : The name of the snippet version
  • description - string : The description of the snippet version
  • text - string : The text of the snippet version
  • createdAt - timestamp : When the snippet version was created
  • createdBy - object : The person that created this snippet version or null
    • id - string : The unique identifier of the person
    • username - string : The username the person
    • email - string : The email of the person
    • name - string : The display of the person
  • dataSource - object : The data source for this snippet version or null
    • id - string : The unique identifier of the data source
    • name - string : The name of the data source
    • configUri - string : The connection URI of the data source

Example request:

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

Example response:

[
  {
    "id": "9b36bbe7-fdba-4c49-bd65-03cc0b81541a",
    "snippetId": "SiK8jWTiKBji4esW",
    "name": "sample",
    "description": "A sample query",
    "text": "SELECT 1",
    "createdAt": "2019-08-14T16:16:03.108Z",
    "createdBy": null
    "dataSource": null
  },
  {
    "id": "e095b986-a2df-42d2-a85e-268a2c458238",
    "snippetId": "SiK8jWTiKBji4esW",
    "name": "sample",
    "description": "A sample query",
    "text": "SELECT 2",
    "createdAt": "2019-08-14T21:01:36.947Z",
    "createdBy": {
      "id": "PkNJRdbtfjFsL6CaC",
      "username": "abrewer",
      "email": "angelique.brewer@example.com",
      "name": "Angelique Brewer"
    },
    "dataSource": {
      "id": "DUGC6IqGQ4DX00Lt0",
      "name": "General Ledger",
      "configUri": "postgresql://gl@db.example.com:5432/gl"
    }
  }
]

List snippets

Returns a list of snippets.

Arguments:

This method has no additional arguments.

Response object:

• An array of Snippet objects
• Each entry in the array is an object with the following properties:
  • id - string : The unique identifier of the snippet
  • activeVersion - object : The active version of this snippet
    • id - string : The unique identifier of the active snippet version
    • name - string : The name of the active snippet version
    • description - string : The description of the active snippet version
    • text - string : The text of the active snippet version
    • dataSource - object : The data source for this snippet version or null
      • id - string : The unique identifier of the data source
      • name - string : The name of the data source
      • configUri - string : The connection URI of the data source
  • isLocked - boolean : Whether the snippet is locked
  • publicAccessLevel - string : The public access level of this snippet for non-owners, either ’none’, ‘read_only’, ‘read_write’, or ‘manage’
  • ownerPerson - object : The person that owns this snippet or null
    • id - string : The unique identifier of the person
    • username - string : The username the person
    • email - string : The email of the person
    • name - string : The display of the person
  • ownerRole - object : The role that owns this snippet or null
    • id - string : The unique identifier of the person
    • name - string : The display of the person
  • createdAt - timestamp : When the snippet was created
  • updatedAt - timestamp : When the snippet 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}/snippet"

Example response:

[
  {
    "id": "SzKWkg28ZEVV96Tp",
    "activeVersion": {
      "id": "1fb93ebe-f3ce-4958-bb03-2bb05f0d7355",
      "name": "Test Snippet",
      "description": "Sample description goes here",
      "text": "SELECT 1",
      "dataSource:" null
    },
    "isLocked": false,
    "publicAccessLevel": "manage",
    "ownerPerson": null,
    "ownerRole": null,
    "createdAt": "2019-08-10T21:34:59.542Z",
    "updatedAt": "2019-08-10T21:34:59.542Z"
  },
  {
    "id": "SmGRTOi51vUKNPYz",
    "activeVersion": {
      "id": "ddaf6347-1f44-4cd5-a1bf-2f577dda687d",
      "name": "Another sample snippet",
      "description": "A basic example of a snippet.",
      "text": "SELECT *\nFROM information_schema.columns",
      "dataSource": {
        "id": "DUGC6IqGQ4DX00Lt0",
        "name": "General Ledger",
        "configUri": "postgresql://gl@db.example.com:5432/gl"
      }
    },
    "isLocked": true,
    "publicAccessLevel": "read_write",
    "ownerPerson": null,
    "ownerRole": {
      "id": "RXNLDrYxE47fNxMx",
      "name": "Marketing"
    },
    "createdAt": "2019-06-22T13:19:15.176Z",
    "updatedAt": "2019-07-26T17:20:21.464Z"
    }
]

Lock a snippet

Locks an existing snippet.

Arguments:

• snippet - string : The identifier of the snippet to lock

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 PUT \
    "${JACKDB_API_URL}/snippet/SiK8jWTiKBji4esW/lock"

Example response:

{}

Retrieve a snippet

Retrieves the details of an existing snippet.

Arguments:

• snippet - The identifier of the snippet to be retrieved

Response object:

• A Snippet object with the following properties:
  • id - string : The unique identifier of the snippet
  • activeVersion - object : The active version of this snippet
    • id - string : The unique identifier of the active snippet version
    • name - string : The name of the active snippet version
    • description - string : The description of the active snippet version
    • text - string : The text of the active snippet version
  • isLocked - boolean : Whether the snippet is locked
  • publicAccessLevel - string : The public access level of this snippet for non-owners, either ’none’, ‘read_only’, ‘read_write’, or ‘manage’
  • ownerPerson - object : The person that owns this snippet or null
    • id - string : The unique identifier of the person
    • username - string : The username the person
    • email - string : The email of the person
    • name - string : The display of the person
  • ownerRole - object : The role that owns this snippet or null
    • id - string : The unique identifier of the person
    • name - string : The display of the person
  • createdAt - timestamp : When the snippet was created
  • updatedAt - timestamp : When the snippet 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}/snippet/ScRthIsjOBol2ULt"

Example response:

{
  "id": "ScRthIsjOBol2ULt",
  "activeVersion": {
    "id": "243f5c00-cbc8-4857-b1c6-e117903ec854",
    "name": "sample",
    "description": "A sample query",
    "text": "SELECT 1"
  },
  "isLocked": false,
  "publicAccessLevel": "none",
  "ownerPerson": {
    "id": "PkNJRdbtfjFsL6CaC",
    "username": "abrewer",
    "email": "angelique.brewer@example.com",
    "name": "Angelique Brewer"
  },
  "ownerRole": null,
  "createdAt": "2019-08-14T16:16:10.448Z",
  "updatedAt": "2019-08-14T16:16:10.448Z"
}

Retrieve a snippet version

Retrieve a version of an existing snippet.

Arguments:

• snippet - string : The identifier of the snippet
• snippetVersion - string : The identifier of the snippet version to retrieve

Response object:

• A Snippet Version object with the following properties:
  • id - string : The identifier of the snippet version
  • snippetId - string : The identifier of the snippet
  • name - string : The name of the snippet version
  • description - string : The description of the snippet version
  • text - string : The text of the snippet version
  • createdAt - timestamp : When the snippet version was created
  • createdBy - object : The person that created this snippet version or null
    • id - string : The unique identifier of the person
    • username - string : The username the person
    • email - string : The email of the person
    • name - string : The display of the person

Example request:

$ curl \
    -H "Accept: application/vnd.jackdb.v2+json" \
    -u "${JACKDB_API_KEY_ID}@api:${JACKDB_API_KEY_SECRET}" \
    "${JACKDB_API_URL}/snippet/SiK8jWTiKBji4esW/version/e095b986-a2df-42d2-a85e-268a2c458238"

Example response:

{
  "id": "e095b986-a2df-42d2-a85e-268a2c458238",
  "snippetId": "SiK8jWTiKBji4esW",
  "name": "sample",
  "description": "A sample query",
  "text": "SELECT 2",
  "createdAt": "2019-08-14T21:01:36.947Z",
  "createdBy": {
    "id": "PkNJRdbtfjFsL6CaC",
    "username": "abrewer",
    "email": "angelique.brewer@example.com",
    "name": "Angelique Brewer"
  }
}

Unlock a snippet

Unlocks an existing snippet.

Arguments:

• snippet - string : The identifier of the snippet to unlock

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 PUT \
    "${JACKDB_API_URL}/snippet/SiK8jWTiKBji4esW/unlock"

Example response:

{}

Update a snippet

Updates the access permissions of an existing snippet.

Arguments:

• snippet - string : The identifier of the snippet to be updated
• publicAccessLevel - string : The public access level of this snippet. One of: ’none’, ‘read_only’, ‘read_write’, or ‘manage’
• owner - string : The owner type of this snippet. One of: ’none’, ‘person’, or ‘role’
• ownerPerson - string : The unique identifier of the person that owns this snippet, if the owner is set to ‘person’
• ownerRole - string : The unique identifier of the role that owns this snippet, if the owner is set to ‘role’

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 POST \
    -d "owner=person&publicAccessLevel=none&ownerPersonId=PkNJRdbtfjFsL6CaC" \
    "${JACKDB_API_URL}/snippet/SzKWkg28ZEVV96Tp"

Example response:

{}

Update a snippet version

Update the active version of an existing snippet.

Arguments:

• snippet - string : The identifier of the snippet
• snippetVersion - string : The identifier of the snippet version to set as active

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 PUT \
    "${JACKDB_API_URL}/snippet/ScRthIsjOBol2ULt/version/243f5c00-cbc8-4857-b1c6-e117903ec854"

Example response:

{}