Flags API

Flag a subject

Description

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

Following operations are supported:

1. POST: Add a new flag on a subject

2. GET: Get flag details

3. PUT: Update the flag reason

4. DELETE: Remove a previously added flag

NOTE: This API is available in version 4.12 and later

Add a flag

This API lets you add a flag on a subject.

URL

POST /integration/flag/

Data Parameters

NameRequiredDescription
flag_typeYesflag_type can be any of the following:
DEPRECATION
ENDORSEMENT
WARNING
flag_reasonNoA reason for adding the flag_type.
NOTE: This field is not required for ENDORSEMENT but is required for the other two flag types.
subjectYesThis is a nested field to describe a subject on which the flag is to be created. It has following fields:
id: unique identifier of the subject for which the flag is to be added
otype: type of the subject.
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 HeaderValue
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 flags are added for the user that makes the POST request.

Get details of a particular flag

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

URL

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

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

Headers

HTTP HeaderValue
TOKEN<your_token>

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

Sucess 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 flags

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

URL

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

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

URL Parameters

NameRequiredDescription
oidNoUnique identifier of a subject.
otypeNoThe type of the subject.
Example: /integration/flag/?oid=1&otype=data
NOTE: Parameters oid and otype need to be used together in a request.
limitNoLimit the number of flags returned.
Example: /integration/flag/?limit=10
skipNoSkip 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 HeaderValue
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 flag reason

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

URL

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

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

Data Parameters

NameRequiredDescription
flag_reasonYesA reason for adding the flag.

NOTE: This API does not let you update flag_reason for ENDORSEMENT type flags as they do not have a reason associated with them.

Sample Request Body

{
    "flag_reason" : "Deprecate this"
}

Headers

HTTP HeaderValue
TOKEN<your_token>

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

Sucess 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 flag

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

URL

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

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

Headers

HTTP HeaderValue
TOKEN<your_token>

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

Sucess Response

Status: 204 NO CONTENT

NOTE: A non-admin user cannot delete other user's 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 flags
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/"

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

# Add a 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 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 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 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 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 flag
response = requests.post('https://alation.yourcompany.com/integration/flag/', data=data, headers=headers)
flag = json.loads(response.text)
print "ID: %s, Reason: %s" % (flag['id'], flag['flag_reason'])

# Update a flag
data = { "flag_reason" : "This has to change." }
response = requests.put('https://alation.yourcompany.com/integration/flag/1/', data=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)