Description

The APIs below allow a user to manipulate trust check flags on a subject. A subject can be a data source, schema, table, column etc.

Following operations are supported:

POST: Add a new trust check flag on a subject
GET: Get trust check flag details
PUT: Update the trust check flag reason
DELETE: Remove a previously added trust check flag

NOTE: This API is available in version 4.12 and later

Add a trust check flag

This API lets you add a trust check flag on a subject.

URL

POST /integration/flag/

Data Parameters

Name	Required	Description
flag_type	Yes	Allowed values are: - `DEPRECATION` - `ENDORSEMENT` - `WARNING`
flag_reason	Sometimes	A reason for adding the flag_type. Required for `DEPRECATION` and `WARNING` flag types. For `ENDORSEMENT` flag types, `flag_reason` must be absent or it must have a blank value.
subject	Yes	This is a nested field to describe a catalog object on which the trust check flag is to be created. It has following fields: - id: Unique identifier of the catalog object for which the flag is to be added. - otype: Object type of the catalog object.For example: `"subject" : {` `"id" : 1,` `"otype" : data` `}`

Sample Request Body

{
    "flag_type": "DEPRECATION",
    "flag_reason": "We do not use this anymore.",
    "subject": {
        "id": 1,
        "otype": "data"
    }
}

Headers

HTTP Header	Value
TOKEN	<your_token>

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Content-Type: application/json

Status: 201 CREATED

Body

{
    "id": 8,
    "flag_type": "DEPRECATION",
    "ts_created": "2017-08-02T03:42:40.462533Z",
    "flag_reason": "Deprecate this data source",
    "subject": {
        "id": "1",
        "url": "/data/1",
        "otype": "data"
    },
    "user": {
        "id": 1,
        "url": "/user/1/",
        "display_name":"User Display Name"
    }
}

NOTE: The trust check flag are added for the user that makes the POST request.

Get details of a particular trust check flag

This API can be used to list details of a trust check flag.

URL

GET /integration/flag/**<flag_id>**

Replace <flag_id> with the unique identifier of a trust check flag.

Headers

HTTP Header	Value
TOKEN	<your_token>

Replace <your_token> with API Token which can be obtained from getToken API call Generate Tokens for the Alation API .

Success Response

Content-Type: application/json

Status: 200 OK

Body

{
    "id": 8,
    "flag_type": "DEPRECATION",
    "ts_created": "2017-08-02T03:42:40.462533Z",
    "flag_reason": "Deprecate this data source",
    "subject": {
        "id": "1",
        "url": "/data/1",
        "otype": "data"
    },
    "user": {
        "id": 1,
        "url": "/user/1/",
        "display_name":"User Display Name"
    }
}

Get all trust check flags

This API is used to list all the trust check flags that exist.

URL

GET /integration/flag/?**<params>**

Replace with your list of parameters. Multiple parameters can be combined as PARAM1&PARAM2

URL Parameters

Name	Required	Description
oid	No	Unique identifier of a subject.
otype	No	The type of the subject. Example: /integration/flag/?oid=1&otype=data NOTE: Parameters `oid` and `otype` need to be used together in a request.
limit	No	Limit the number of trust check flags returned. Example: /integration/flag/?limit=10
skip	No	Skip a number of records and return the rest. limit and skip are used for pagination of the results. Example: /integration/flag/?skip=10

Headers

HTTP Header	Value
TOKEN	<your_token>

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Content-Type: application/json

Status: 200 OK

Body

[
    {
        "id": 77,
        "flag_type": "DEPRECATION",
        "flag_reason": "Should not use this table",
        "ts_created": "2017-08-08T03:39:27.608519Z",
        "subject": {
            "url": "/table/1/",
            "otype": "table",
            "id": 1
        },
        "user": {
            "id": 1,
            "url": "/user/1/",
            "display_name": "Test User1"
        }
    },
    {
        "id": 82,
        "flag_type": "WARNING",
        "flag_reason": "Might have old data",
        "ts_created": "2017-08-08T17:58:02.079547Z",
        "subject": {
            "url": "/table/2/",
            "otype": "table",
            "id": 2
        },
        "user": {
            "id": 1,
            "url": "/user/1/",
            "display_name": "Test User2"
        }
    }
]

Update a trust check flag reason

This API is used to update a given trust check flag's reason.

URL

PUT /integration/flag/**<flag_id>**/

Replace <flag_id> with the unique identifier of a trust check flag.

Data Parameters

Name	Required	Description
flag_reason	Yes	A reason for adding the trust check flag. You can't update `flag_reason` for `ENDORSEMENT` flag types as they don't have a reason.

Sample Request Body

{
    "flag_reason" : "Deprecate this"
}

Headers

HTTP Header	Value
TOKEN	<your_token>

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Content-Type: application/json

Status: 200 OK

Body

{
    "id": 8,
    "flag_type": "DEPRECATION",
    "ts_created": "2017-08-02T03:42:40.462533Z",
    "flag_reason": "Deprecate this.",
    "subject": {
        "id": "1",
        "url": "/data/1",
        "otype": "data"
    },
    "user": {
        "id": 1,
        "url": "/user/1/",
        "display_name":"User Display Name"
    }
}

Delete a trust check flag

This API is used to delete an existing trust check flag from a subject.

URL

DELETE /integration/flag/**<flag_id>**/

Replace <flag_id> with the unique identifier of a trust check flag.

Headers

HTTP Header	Value
TOKEN	<your_token>

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Status: 204 NO CONTENT

NOTE: A non-admin user cannot delete other users' trust check flags.

Error Response

Invalid Token

Status: 403 Forbidden

Body

{
   "detail": "Authentication failed"
}

Missing Token Header

Status: 403 Forbidden

Body

{
    "detail": "Missing API token."
}

NOTE: The Error responses are common to all of the requests above.

Code Samples

cURL

#!/bin/bash

# This is an example token. Please replace this with your token.
API_TOKEN="2abcd-4c04-4c21-8692-eda27a877f90"

BASE_URL="https://alation.yourcompany.com/integration/flag"

# Get all trust check flags
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/"

# Get details of a particular trust check flag
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/1/"

# Add a trust check flag
curl -X POST "${BASE_URL}/" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" -d '{
    "flag_type" : "WARNING",
    "subject": {
        "id":3,
        "otype":"schema"
    },
    "flag_reason" : "This schema looks fishy."
}'

# Update a trust check flag
curl -X PUT "${BASE_URL}/1/" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" -d '{ "flag_reason" : "This might be corrupted data." }'

# Delete a trust check flag
curl -X DELETE "${BASE_URL}/1/" -H "TOKEN: ${API_TOKEN}"

Python

import requests
import json

# This is an example token. Please replace this with your token.
headers = {'Token': '2abcd-4c04-4c21-8692-eda27a877f90'}

# Get all trust check flags
response = requests.get('https://alation.yourcompany.com/integration/flag/', headers=headers)
flags = json.loads(response.text)
for flag in flags:
    print ("ID: %s, Reason: %s" % (flag['id'], flag['flag_reason']))

# Get details of a particular trust check flag
response = requests.get('https://alation.yourcompany.com/integration/flag/1/', headers=headers)
flag = json.loads(response.text)
print ("ID: %s, Reason: %s" % (flag['id'], flag['flag_reason']))

data = {
    "flag_type" : "WARNING",
    "subject": {
        "id":3,
        "otype":"schema"
    },
    "flag_reason" : "This schema looks fishy."
}

# Add a trust check flag
response = requests.post('https://alation.yourcompany.com/integration/flag/', json=data, headers=headers)
flag = json.loads(response.text)
print ("ID: %s, Reason: %s" % (flag['id'], flag['flag_reason']))

# Update a trust check flag
data = { "flag_reason" : "This has to change." }
response = requests.put('https://alation.yourcompany.com/integration/flag/1/', json=data, headers=headers)
flag = json.loads(response.text)
print ("ID: %s, Reason: %s" % (flag['id'], flag['flag_reason']))

# Delete a flag
response = requests.delete('https://alation.yourcompany.com/integration/flag/1/', headers=headers)
print ("Status Code: %s" % (response.status_code))