API Guides

Get Access Token

The access token is used in the request header Authorization: Bearer <COPY ACCESS CODE HERE>

CODE

# REPLACE: <USER>, <PASSWORD>
curl -X POST -u "know-app:" \
  -d "grant_type=password&username=<USER>&password=<PASSWORD>&scope=openid profile email" \
  https://<domain>/keycloak/auth/realms/kada/protocol/openid-connect/token
  
# Response. The access_token will be used to authenticate API calls to KADA.
{
    "access_token": "..",
    "expires_in": 7200,
    "refresh_expires_in": 86400,
    "refresh_token": "...",
    "token_type": "bearer",
    "id_token": "...",
    "not-before-policy": 0,
    "session_state": "...",
    "scope": "openid profile email"
}

export ACCESS_TOKEN=<ACCESS TOKEN FROM RESPONSE>

Get an object

Get the table with name ‘customer’

CODE

curl --location \
  --request GET 'https://<domain>/api/tables?name=customer' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Get fully qualified table name: table123, in schema3 in db2 in host1.

CODE

curl --location \
  --request GET 'https://<domain>/api/tables?signature=host1.db2.schema3.table123' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Updating a description

<TABLE ID> can be found from the Get object call.

CODE

curl --location --request PUT 'https://<domain>/api/tables/<TABLE ID>' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "description": "Add your description here",
    "replace_date": null
}'

Adding a tag to a table

Create a tag

CODE

curl --location --request POST 'https://<domain>/api/tags' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "description": "Add your tag description here",
    "name": "tag_name"
}'

Link the tag to an object.

<TABLE ID> is returned from the Get object call

<TAG ID> is returned from the Get Tags or Create tag call

CODE

curl --location \
  --request PUT 'https://<domain>/api/tables/<TABLE_ID>/related?object_id=<TAG_ID>&relationship=TAGGED_BY' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Delete a tag from an object

CODE

curl --location \
  --request DELETE 'https://<domain>/api/tables/<TABLE_ID>/related?object_id=<TAG_ID>&relationship=TAGGED_BY' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Adding a property to a object

A property name is unique for a given object

<OBJECT ID> can be found from the Get object APIs.

CODE

curl --location \
  --request PUT 'https://<domain>/api/additionalproperties/<OBJECT ID>' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-raw '[
    {
        "operation": "ADD_OR_UPDATE",
        "name": "new property 123",
        "type": "STRING",
        "value": "PASS",
        "description": "Add a property description here"
    },
    {
        "operation": "CLEAR",
        "name": "existing property",
        "type": "STRING",
        "value": "",
        "description": ""
    }
]'

Get a collection template

Get the Classification collection.

CODE

curl --location \
  --request GET 'https://domain/api/collections?name=Classification' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Response - note the properties which will be used to create collection instances.

CODE

{
    "id": "e1fd2337-1b0e-3841-8d60-7c85daa1707e",
    "id_seq": 2,
    ...
    "properties": [
        {
            "allowed_values": [],
            "data_type": "TEXT_FIELD",
            "description": "Add a name for the instance",
            "id": "1",
            "name": "name",
            "required": true
        },
        {
            "allowed_values": [],
            "data_type": "TEXT_BOX",
            "description": "Add a description for the instance",
            "id": "2",
            "name": "description",
            "required": false
        },
        {
            "allowed_values": [],
            "data_type": "USER_LOOKUP_FILTERED",
            "description": "Add an owner for the instance",
            "filter": "16e05af2-13fa-301d-b7fa-69d48bc71d7d",
            "id": "-1",
            "name": "data owner",
            "required": false
        },
        {
            "allowed_values": [],
            "data_type": "USER_LOOKUP_FILTERED_MULTI",
            "description": "Add steward(s) for the instance",
            "filter": "d13d6b10-a535-3718-854d-459f086ad057",
            "id": "-2",
            "name": "data steward",
            "required": false
        }
    ]
    ...
    "score": 5.0,
    "short_name": "classification",
    "signature": "platform/classification",
    "source_id": 1000,
    "updated_at": "2021-10-14T16:02:13.139799+00:00"
}

Creating a collection instance

First create a collection and define the template in KADA via the Admin portal.

Use the properties field from the Get collection template to map the properties values to the property id.

<COLLECTION ID> Use Get collection template to find the collection id

First create the collection instance

CODE

curl --location --request POST 'https://<domain>/api/collectioninstances' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "collection_id": "<COLLECTION ID>",
  "description": "Open information",
  "name": "Public",
  "properties": {
    "1": "Public",
    "2": "Open information",
    "-1": "",
    "-2": []
  }
}'

Linking the collection instance to a table.

<TABLE ID> the table being linked to the collection

<COLLECTION INSTANCE ID> the collection instance being linked.

CODE

curl --location \
  --request PUT 'https://<domain>/api/tables/<TABLE ID>/related?object_id=<COLLECTION INSTANCE ID>&relationship=MEMBER_OF' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Adding and Steward to a table

Similarly to add an owner use the relationship relationship=OWNED_BY

CODE

curl --location \
  --request PUT 'https://<domain>/api/tables/<TABLE ID>/related?object_id=<user-id>&relationship=STEWARDED_BY' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Creating manual lineage to an upstream table

<TABLE ID> this is the downstream table. Use Get to find the table id.

<UPSTREAM TABLE ID> this is the source table. Use Get to find the table id

CODE

curl --location \
  --request PUT 'https://<domain>/api/tables/<TABLE ID>/related?object_id=<UPSTREAM TABLE ID>&relationship=SOURCE_FROM' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"