Querying DSEs

This page shows some examples on how to use the dScribe API to query dses.

Get DSEs

List existing dses

Get a (paginated) list of the dses you have documented in dScribe

GEThttps://__tenant__.dscribedata.com/api/dses

Authorization

BearerAuth

Query parameters

Response

200500

Successful operation

Body

application/json

metadataMetadata (object)

resultsarray of Dse (object)

Request

JavaScriptCurlPython

const response = await fetch('https://__tenant__.dscribedata.com/api/dses', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200

{
  "metadata": {},
  "results": [
    {
      "id": "text",
      "name": "text",
      "parent": "text",
      "key_constraint": "text",
      "is_leaf": false,
      "assets": [
        "text"
      ],
      "dataset_id": "text",
      "description": "text"
    }
  ]
}

This endpoint will list your available dses. The query is paginated to the first 15 items. You can use the page and pageSize params to adjust this to your needs.

const url = "https://{your_tenant}.dscribedata.com/api/dses";
const authToken = "yholmghj8§hbfg...";

fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${authToken}`,
    "Content-Type": "application/json",
  },
});

The response will look something like this.

Note the last page argument in the metadata object. We added it for your convenience to check if more assets need to be fetched.

{
  "metadata": {
    "page": 1,
    "pageSize": 20,
    "total": 3,
    "last_page": 1
  },
  "results": [
    {
      "id": "4030b7de-104f-4547-8d90-030def80c1cf",
      "name": "dse",
      "parent": "123",
      "dataset_id": "42d5b4ca-7c57-4af7-bb4b-ba6f3d35ecd0",
      "description": null,
      "is_leaf": false,
      "assets": ["123"],
      "key_constraint": "primary"
    },
    {
      "id": "2cec0d80-7477-400c-9297-ae69759cacd7",
      "name": "test123",
      "parent": "123",
      "dataset_id": "27c87108-303a-4d29-815f-ab450190aa62",
      "description": null,
      "is_leaf": false,
      "assets": ["123"],
      "key_constraint": "secondary"
    },
    {
      "id": "bf99b67e-2fdf-4823-82f7-6f518d142f7a-999340451",
      "name": "Extract",
      "parent": "123",
      "dataset_id": "27c87108-303a-4d29-815f-ab450190aa62",
      "description": null,
      "is_leaf": false,
      "assets": ["123"],
      "key_constraint": null
    }
  ]
}

Search DSEs

Search through existing dses

Get a (paginated) list of the dses you have documented in dScribe based on the defined filters

POSThttps://__tenant__.dscribedata.com/api/dses/search

Authorization

BearerAuth

Query parameters

Body

application/json

The filters passed to the request.

whereobject

Response

200500

Successful operation

Body

application/json

metadataMetadata (object)

resultsarray of Dse (object)

Request

JavaScriptCurlPython

const response = await fetch('https://__tenant__.dscribedata.com/api/dses/search', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "metadata": {},
  "results": [
    {
      "id": "text",
      "name": "text",
      "parent": "text",
      "key_constraint": "text",
      "is_leaf": false,
      "assets": [
        "text"
      ],
      "dataset_id": "text",
      "description": "text"
    }
  ]
}

If you want a bit more control on the dses that are returned, you can use the search endpoint. You can search on dataset_id (so the asset the dse is linked too), the parent DSE or the name.

const url = "https://{your_tenant}.dscribedata.com/api/dses/search";
const authToken = "yholmghj8§hbfg...";

fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${authToken}`,
    "Content-Type": "application/json",
  },
  data: JSON.stringify({
    where: {
      name_contains: "finance",
      dataset_id: ["42d5b4ca-7c57-4af7-bb4b-ba6f3d35ecd0"],
      parent: ["123"],
    },
  }),
});

Find one DSE

Find one specific dse

Get a dse based on the passed id

GEThttps://__tenant__.dscribedata.com/api/dses/{id}

Authorization

BearerAuth

Path parameters

id*string

Response

200500

Successful operation

Body

application/json

idstring

name*string

parentstring

use the id of the parent dse if the you want to display the dses hierarchically within dScribe

key_constraintstring

Accepted values are primary, foreign and unique

is_leafboolean

Convenience property exposed to help you determine if the DSE has a parent

assetsarray of string

Assets the DSE is linked too

dataset_idstring

The dataset id the dse is linked too. If the DSEs are created together with the dataset (via POST /api/assets), it will automatically use the created dataset id

descriptionstring

Request

JavaScriptCurlPython

const response = await fetch('https://__tenant__.dscribedata.com/api/dses/{id}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200

{
  "id": "text",
  "name": "text",
  "parent": "text",
  "key_constraint": "text",
  "is_leaf": false,
  "assets": [
    "text"
  ],
  "dataset_id": "text",
  "description": "text"
}

For some integrations it might be useful to only fetch one asset.

const url = "https://{your_tenant}.dscribedata.com/api/dses/:id";
const authToken = "yholmghj8§hbfg...";

fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${authToken}`,
    "Content-Type": "application/json",
  },
});

Give a response like so:

{
  "id": "4030b7de-104f-4547-8d90-030def80c1cf",
  "name": "dse",
  "parent": "123",
  "dataset_id": "42d5b4ca-7c57-4af7-bb4b-ba6f3d35ecd0",
  "description": null,
  "is_leaf": false,
  "assets": ["123"],
  "key_constraint": "primary"
}