HomeGuidesRecipesAPI Reference
Alation Help Center

Tags API

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

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 with your list of parameters. Multiple parameters can be combined as PARAM1&PARAM2

URL Parameters

NameRequiredDescription
oidNoUnique identifier of a catalog object.
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.
otypeNoThe object type of a catalog object. See the table below for a list of valid object types. The object type should not be put in quotes.
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 orderby 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 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 in the Alation catalog
otype: Type of the subject
id: Unique identifier of the subject in the 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
YesType of a subject
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 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 with the unique identifier of the tag in 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 $#)
# 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

NameotypeDescription
ArticlearticleAn article in the Alation catalog
Business Policybusiness_policyA business policy in the Policy Center
Column (Attribute)attributeA column inside a table
Column Value (Attribute Value)attribute_valueA column value
Data SourcedataA data source in the Alation catalog
DirectorydirectoryA directory inside file system
FilefileA file inside a file system
File SystemfilesystemA file system in the Alation catalog
FunctionfunctionA function in the Alation catalog
Glossaryglossary_v3A glossary in the Alation catalog. Refers to new glossaries, not article groups.
Glossary Termglossary_termA glossary term in the Alation catalog. Refers to new glossary terms, not articles.
Policy Grouppolicy_groupA policy group in the Policy Center.
Propagated Catalog Setpropagated_catalog_setThe metadata shared by objects in a catalog set. Use this otype to add a tag to all objects in the set
QueryqueryA query written in Compose
Report Collectionreport_collectionA BI server project in the Alation catalog
Report Objectreport_objectA BI server report or dashboard in the Alation catalog
Report Sourcereport_sourceA BI server server in the Alation catalog
SchemaschemaA schema of a table in the Alation catalog
TabletableA table inside a schema
Tableau Datasourcetableau_datasourceA Tableau data source (connection)
Tableau Servertableau_serverA Tableau server in the Alation catalog
Tableau Sheettableau_sheetA Tableau report or dashboard in the Alation catalog
Tableau Workbooktableau_workbookA Tableau workbook in the Alation catalog
UseruserA user
User groupgroupprofileA user group