Tags API

Description

This API allows users to manipulate tags on a subject. See subjects that can be tagged at the bottom of this page for a list of subjects that can be tagged.

NOTE: This API is available in version 4.14 and later.

The following operations are supported (in version 4.14 and later):

1. POST: Add a tag to a subject.

2. GET: Get all tags in Alation catalog as well as get all subjects tagged with a specific tag.

3. DELETE: Remove a tag from a subject.

The following operations are supported (in version 5.9 and later):

1. GET: Get details of a specific tag.

2. PATCH: Update a tag's name or description.

Add tag to a subject

This API lets you add a tag to a subject.

URL

Replace <tag_name> with the name of a tag. If the specified <tag_name> does not exist inside Alation catalog, a new one is created.

NOTE:

a) If a tag name consists of special or unicode characters, such as #, Г, spaces etc., it has to be url encoded for a successful request.

b) Only admin users can add a tag to propagated_catalog_set (shared field of a Catalog set).

Data Parameters

Sample Request Body

{
    "oid": 1,
    "otype": "table"
}

Headers

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": 1,
    "name": "Test Tag",
    "description": "<p>This is a test tag</p>",
    "number_of_objects_tagged": 2,
    "ts_created": "2017-09-21T20:08:09.474103Z",
    "url": "/tag/1/"
}

Get all tags in Alation catalog

This API is used to list all the tags that exist inside Alation catalog.

URL

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

URL Parameters

Headers

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": 1,
        "name": "Test Database",
        "description": "<p>This tag is for test db's</p>",
        "number_of_objects_tagged": 1,
        "ts_created": "2017-09-26T17:40:07.456130Z",
        "url": "/tag/1/"
    },
    {
        "id": 2,
        "name": "@Mentions",
        "description": "",
        "number_of_objects_tagged": 3,
        "ts_created": "2017-09-26T18:26:07.144050Z",
        "url": "/tag/2/"
    }
]

Get all subjects tagged with a certain tag

This API is used to get all the subjects tagged with a given tag name.

URL

Replace <tag_name> with the name of a tag.

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

NOTE: If a tag name consists of special or unicode characters, such as #, Г, spaces etc., it has to be url encoded for a successful request.

URL Parameters

Headers

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

[
    {
        "ts_tagged": "2017-09-21T20:10:22.181393Z",
        "subject": {
            "url": "/catalog_set/2/",
            "otype": "propagated_catalog_set",
            "id": 2
        }
    },
    {
        "ts_tagged": "2017-09-22T23:57:29.682968Z",
        "subject": {
            "url": "/user/1/",
            "otype": "user",
            "id": 1
        }
    }
]

Remove a tag from a subject

This API allows you to remove a tag from a subject

URL

NOTE: Only admin users can remove a tag from propagated_catalog_set (shared field of a Catalog set)

Path Parameters

Headers

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

Success Response

Status: 204 NO CONTENT

NOTE: If the tag to be removed does not have any other subject associated with it, the tag gets deleted and the response status is 200 OK.

Get details of a specific tag

This API allows you to get details of a specific tag

URL

Replace with the unique identifier of the tag inside Alation.

Headers

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": 1,
    "name": "Test Database",
    "description": "<p>This tag is for test db's</p>",
    "number_of_objects_tagged": 1,
    "ts_created": "2017-09-26T17:40:07.456130Z",
    "url": "/tag/1/"
}

Update a tag

This API allows you to update either a tag's name or description or both.

URL

Replace with the unique identifier of the tag in Alation.

Data Parameters

Sample Request Body

{
    "name": "Test Tag",
    "description": "<p>This is a test tag</p>"
}

Headers

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": 1,
    "name": "Test Tag",
    "description": "<p>This is a test tag</p>",
    "number_of_objects_tagged": 2,
    "ts_created": "2017-09-21T20:08:09.474103Z",
    "url": "/tag/1/"
}

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/tag"

# Get all tags
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/"

# Get tags of a particular subject
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/?oid=1&otype=data"

# Add a tag to a subject
curl -X POST "${BASE_URL}/Employees/subject/" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" -d '{
        "oid" : 2,
        "otype" : "schema"
    }'

# Get all subjects with a certain tag
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/Employees/subject/"

# Remove a tag from a subject
curl -X DELETE "${BASE_URL}/Employees/subject/schema/2/" -H "TOKEN: ${API_TOKEN}"

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

# Update a tag's name
curl -X PATCH "${BASE_URL}/1/" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" -d '{
    "name": "new tag name"
}'

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 tags
response = requests.get('https://alation.yourcompany.com/integration/tag/', headers=headers)
tags = json.loads(response.text)
for tag in tags:
    print "ID: %s, Name: %s" % (tag['id'], tag['name'])

# Get tags for a specific subject
response = requests.get('https://alation.yourcompany.com/integration/tag/?oid=1&otype=data', headers=headers)
tags = json.loads(response.text)
for tag in tags:
    print "ID: %s, Name: %s" % (tag['id'], tag['name'])

data = {
    "oid": "4d577658-578d-7799-e273-c7ed218918",
    "otype": "file"
}

# Add a tag to a subject
response = requests.post('https://alation.yourcompany.com/integration/tag/Employees/subject/', data=data, headers=headers)
tag = json.loads(response.text)
print "ID: %s, Name: %s" % (tag['id'], tag['name'])

# Add a url encoded tag (the tag name is #% profit in $#)
# Alternatively you can use urllib.quote('#% profit in $#') to urlencode the tag
response = requests.post('https://alation.yourcompany.com/integration/tag/%23%25%20profit%20in%20%24%23/subject/', data=data, headers=headers)
tag = json.loads(response.text)
print "ID: %s, Name: %s" % (tag['id'], tag['name'])

# Get all subjects tagged
response = requests.get('https://alation.yourcompany.com/integration/tag/Employees/subject/', headers=headers)
subjects = json.loads(response.text)
for subject in subjects:
    print "ID: %s, URL: %s" % (subject['subject']['id'], subject['subject']['url'])

# Remove a tag
response = requests.delete('https://alation.yourcompany.com/integration/tag/Employees/subject/schema/2/', headers=headers)
print(response.status_code)

# Get details of a tag
response = requests.get('https://alation.yourcompany.com/integration/tag/1/', headers=headers)
tag = json.loads(response.text)
print "Name: %s" % (tag['name'])

# Update a tag's name and description
data = {
    "name": "new tag name",
    "description": "new description"
}
response = requests.patch('https://alation.yourcompany.com/integration/tag/1/', data=data, headers=headers)
tag = json.loads(response.text)
print "Name: %s, Description: %s" % (tag['name'], tag['description'])

Subjects that can be tagged