Tags API

Description

This API enables users to manage tags on Alation objects.

The following operations are supported:

1. GET: Retrieve all tags from the Alation catalog, get details of a specific tag, or retrieve all objects associated with a specific tag.
2. POST: Add a tag to an object.
3. PATCH: Update a tag's name or description.
4. DELETE: Remove a tag from an object.

Objects that can be tagged

Get all tags in Alation catalog

This API can be used to list all tags that exist in the Alation catalog.

URL

Replace <params> with your desired parameters. Multiple parameters can be combined using & (for example, PARAM1&PARAM2).

Path Parameters

Headers

Replace <your_token> with an API token obtained from the 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 objects tagged with a certain tag

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

URL

Replace <params> with your desired parameters. Multiple parameters can be combined using & (for example, 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.

Path Parameters

Headers

Replace <your_token> with an API token obtained from the 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
        }
    }
]

Get details of a specific tag

This API allows you to get details of a specific tag.

URL

Path Parameters

Headers

Replace <your_token> with an API token obtained from the 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/"
}

Add tag to an object

This API lets you add a tag to an object.

URL

Replace <tag_name> with the name of a tag. If the specified <tag_name> does not exist inside the 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).

Path Parameters

Data Parameters

Sample Request Body

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

Headers

Replace <your_token> with an API token obtained from the 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/"
}

Update a tag

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

URL

Path Parameters

Data Parameters

Sample Request Body

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

Headers

Replace <your_token> with an API token obtained from the 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/"
}

Remove a tag from an object

This API allows you to remove a tag from an object.

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 an API token obtained from the getToken API call (Get API Token).

Success Response

Status: 204 NO CONTENT

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

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 object
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/?oid=1&otype=data"

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

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

# Remove a tag from an object
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 object
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 an object
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 objects tagged
response = requests.get('https://alation.yourcompany.com/integration/tag/Employees/subject/', headers=headers)
objects = json.loads(response.text)
for object in objects:
    print ("ID: %s, URL: %s" % (object['subject']['id'], object['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']))