Tags API

Tags API

Description

This API allows users to manipulate tags on a subject. Please refer subjects that can be tagged to get 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

POST /integration/tag/**<tag_name>**/subject/

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

NameRequiredDescription
oidYesUnique identifier of a subject inside Alation catalog.
NOTE: oid can either be an integer or a string (in case of files)
otypeYesThe type of a subject.
NOTE: oid and otype both need to be used together in a request.

Sample Request Body

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

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": 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/"
}
NameDescription
idUnique identifier of a tag inside Alation catalog
nameName of the tag
descriptionDescription of the tag
num_of_objects_taggedNumber of subjects tagged with the tag
ts_createdTimestamp the tag was created.
The value is in UTC/GMT timezone.
urlLocation of the tag inside Alation catalog

Get all tags in Alation catalog

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

URL

GET /integration/tag/?**<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/tag/?oid=1&otype=data
NOTE: Parameters oid and otype need to be used together in a request. When they are specified the results are filtered to the tags on the subject specified by the otype and oid.
limitNoLimit the number of tags returned.
Example: /integration/tag/?limit=10
skipNoSkip a number of records and return the rest. limit and skip are used for pagination of the results.
Example: /integration/tag/?skip=10
order_byNoSort the results based on a value.
order_by supports two values:
num_of_objects_tagged - Sort the results based on the number of subjects tagged against a certain tag in ascending order. This is the default ordering when order_by is not specified.
-num_of_objects_tagged - Sort the results based on the number of subjects tagged against a certain tag in descending order.
Example: /integration/tag/?order_by=-num_of_objects_tagged

Note the - before num_of_objects_tagged for descending sort

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": 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

GET /integration/tag/**<tag_name>**/subject/?**<params>**

Replace <tag_name> with the name of a tag.

Replace <params> 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

NameRequiredDescription
limitNoLimit the number of tags returned.
Example: /integration/tag/Employees/subject/?limit=10
skipNoSkip a number of records and return the rest. limit and skip are used for pagination of the results.
Example: /integration/tag/Employees/subject/?skip=10
order_byNoSort the results based on a value.
order_by supports two values:
ts_tagged - Sort the results in ascending order of the timestamp the tag was added to the subject.
-ts_tagged - Sort the results in descending order of the timestamp the tag was added to the subject.
Example: /integration/tag/Employees/subject/?order_by=-ts_tagged

Note the - before ts_tagged for descending sort

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

[
    {
        "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
        }
    }
]
NameDescription
ts_taggedRepresents the timestamp the subject was tagged at.
The value is in UTC/GMT timezone.
subjectThis a nested field to describe a subject that is tagged with the given tag name. It has following fields:
url: Location of the subject inside Alation catalog
otype: Type of the subject
id: Unique identifier of the subject inside Alation catalog

Remove a tag from a subject

This API allows you to remove a tag from a subject

URL

DELETE /integration/tag/**<tag_name>**/subject/**<otype>**/**<oid>**/

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

Path Parameters

NameRequiredDescription
<tag_name>YesName of a tag
<otype>YesType of a subject
<oid>YesUnique identifier of a subject

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

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

GET /integration/tag/**<id>**/

Replace <id> with the unique identifier of the tag inside Alation.

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": 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

PATCH /integration/tag/**<id>**/

Replace <id> with the unique identifier of the tag inside Alation.

Data Parameters

NameRequiredDescription
nameNoThe new name of the tag.
NOTE: Only admin users can update a tag's name
descriptionNoThe new description of the tag.
NOTE:
1. Description can be updated by any user.
2. Either of name or description is required in the body of the request.

Sample Request Body

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

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": 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 $#)
# Alernatively 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

NameotypeDescription
ArticlearticleRepresents an article inside Alation catalog
Column (Attribute)attributeRepresents a column inside a table
Column Value (Attribute Value)attribute_valueRespresents a column value
DatasourcedataRepresents a data source inside Alation catalog
DirectorydirectoryRepresents a directory inside file system
FilefileRepresents a file inside a file system
File SystemfilesystemRepresents a file system inside Alation catalog
Propagated Catalog Setpropagated_catalog_setRepresents the metadata shared by objects in a catalog set. Use this otype to add a tag to all objects in the set
QueryqueryRepresents queries written in Compose
Report Collectionreport_collectionRepresents a BI server project inside Alation catalog
Report Objectreport_objectRepresents a BI server report or dashboard inside Alation catalog
Report Sourcereport_sourceRepresents a BI server server inside Alation catalog
SchemaschemaRepresents a schema of a table inside Alation catalog
TabletableRepresents a table inside a schema
Tableau Datasourcetableau_datasourceRepresents a tableau data source (connection)
Tableau Servertableau_serverRepresents a tableau server inside Alation catalog
Tableau Sheettableau_sheetRepresents a tableau report or dashboard inside Alation catalog
Tableau Workbooktableau_workbookRepresents a tableau workbook inside Alation catalog
UseruserRepresents a user
User groupgroupprofileRepresents a user group