Article Overview

Articles API

Description

The APIs below allow a user to manipulate articles in the Alation Catalog.

Following operations are supported:

1. POST: Add a new article.

2. GET: Get a specific article or a list of all articles.

3. PUT: Update an existing article.

4. DELETE: Remove an existing article.

5. POST: Resurrect a deleted article.

NOTE: This API is available in version 4.19 and later

Create an article

This API lets you create a new article in the Alation catalog, along with a list of custom templates and children.

URL

POST /integration/v1/article/

Data Parameters

NameRequiredDescription
titleYesTitle of the article.
bodyYesBody of the article.
privateNoIs the article private? (By default, it is public)
custom_templatesNoList of custom-template IDs, which can be obtained from CustomTemplates API call.(Custom Template)
Example: [1,2]
childrenNoList of children (can be article or table)
Example: [{"id": 1, "otype": "Table"}, {"id": 3, "otype": "Article"}]
agile_approval_enabledNotrue when Agile Approval is enabled on the article. For new Articles, this defaults to false.

Sample Request Body

{
    "title": "Articles API",
    "body": "<p>Hello World</p>",
    "custom_templates": [1,3],
    "children": [{"id": 1, "otype": "Article"}, {"id": 3, "otype": "Table"}],
    "agile_approval_enabled": true
}

Headers

HTTP HeaderValue
Token<your_token>
Content-Typeapplication/json

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

Success Response

Content-Type: application/json

Status: 201 CREATED

Body

{
    "agile_approval_enabled": true,
    "attachments": [],
    "author": {
        "id": 1,
        "display_name": "user-display-name",
        "email": "[email protected]",
        "username": "username",
        "url": "/user/1/"
    },
    "body": "<p>Hello World</p>",
    "children": [
        {
            "id": 1,
            "otype": "article",
            "title": "Database information",
            "url": "/article/1/database-information"
        },
        {
            "id": 3,
            "otype": "table",
            "name": "table3",
            "title": "Sales information",
            "url": "/table/3/"
        }
    ],
    "custom_fields": [],
    "custom_templates": [
        {
            "id": 1,
            "title": "Business glossary template"
        },
        {
            "id": 3,
            "title": "Additional Custom Fields"
        }
    ],
    "editors": [
        {
            "id": 1,
            "display_name": "user-display-name",
            "email": "[email protected]",
            "username": "username",
            "url": "/user/1/"
        }
    ],
    "has_children": false,
    "id": 18,
    "private": false,
    "title": "Articles API",
    "ts_updated": "2017-12-05T23:24:04.000907Z",
    "ts_created": "2017-12-05T23:24:04.000907Z",
    "url": "/article/18/articles-api"
}

Read an article

This API can be used to list the following details of an article:

NameDescription
idUnique identifier of the article
titleTitle of the article
ts_updatedTimestamp when the article is last updated
ts_createdTimestamp when the article is created
agile_approval_enabledtrue when Agile Approval is enabled on the article. For new Articles, this defaults to false.
attachmentsList of attachments of the article
authorAuthor details like id, username, display_name, email and url
bodyBody of the article
childrenChildren of the article, can be tables or articles
custom_fieldsnon empty custom_fields of the article:
Custom Fields Format API
custom_templatesList of custom_templates assigned to the article
editorsList of all the contributors of the article, contains id, username, display_name, email and url
has_childrenBoolean to indicate if article has children
privateBoolean to indicate if the article is private
urlURL of the article

The body of the article will be interpreted as HTML. Certain tags are kept and others are stripped. Refer to HTML Sanitization API to understand which tags and styles are white-listed.

NOTE: Refer to Custom Fields Format API for understanding the various custom_fields and their types.

URL

GET /integration/v1/article/**<article_id>**/

Replace <article_id> with the unique identifier of an article.

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

{
    "agile_approval_enabled": true,
    "attachments": [
        {
            "otype": "doc",
            "title": "someschema.json",
            "description": "",
            "download_url": "/media/docs/article/1/someschema.json",
            "id": 1
        }
    ],
    "author": {
        "id": 1,
        "display_name": "user-display-name",
        "email": "[email protected]",
        "username": "username",
        "url": "/user/1/"
    },
    "body": "<p>article body</p>",
    "children": [
        {
            "id": 4,
            "otype": "article",
            "title": "Child Article",
            "url": "/article/4/child-article"
        },
        {
            "id": 6,
            "otype": "table",
            "name": "child_table",
            "title": "Child Table",
            "url": "/table/6/"
        }
    ],
    "custom_fields": [
        {
            "value_type": "user",
            "field_name": "Steward",
            "value": "TestUser1"
        },
        {
            "value_type": "schema",
            "field_name": "policy",
            "value": "test_metadata_extraction_emp1"
        },
    ],
    "custom_templates": [
        {
            "id": 17,
            "title": "Business Glossary"
        }
    ],
    "editors": [
        {
            "id": 1,
            "display_name": "user-display-name",
            "email": "[email protected]",
            "username": "username",
            "url": "/user/1/"
        }
    ],
    "has_children": false,
    "id": 18,
    "private": false,
    "title": "Articles API",
    "ts_updated": "2018-01-09T02:25:39.452678Z",
    "ts_created": "2017-12-05T23:24:04.000907Z",
    "url": "/article/18/articles-api"
}

Read and filter on all Articles

This API is used to list and filter on all the active articles. Deleted articles are ignored. Users can see all public articles, the private articles where they are authors, and the private articles to which they have been granted access.

URL

GET /integration/v1/article/?**<params>**

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

URL Parameters

NameRequiredData TypeDescription
titleNostringFilter articles with this title.
Example: /integration/v1/article/?title=Articles API
title__icontainsNostringFilter articles whose titles contain this word.
Example: /integration/v1/article/?title__icontains=sales
has_childrenNobooleanFilter articles with/without children.
Example: /integration/v1/article/?has_children=True
custom_field_templatesNolist of custom-template IDsFilter articles with atleast one custom_template belonging to this list.
Example: /integration/v1/article/?custom_field_templates=[1,2]
valuesNocomma separated list of field_namesFields that needs to be returned for each article.
Example: /integration/v1/article/?title=Sales&values=id,custom_templates

Articles can be filtered to those relevant to a particular object. Articles are considered relevant to an object if they have a reference to that object in their description or custom fields. To filter to relevant articles, pass the following params

NameRequiredDescription
otypeYesOtype of the object, whose relevant articles are desired.
oidYesOid of the object, whose relevant articles are desired.
include_sharedNoBoolean to include shared articles or not.

For example: /integration/v1/article/?otype=table&oid=1 would return all the articles that have this table mentioned in their body or custom-fields.

Headers

HTTP HeaderValue
Token<your_token>
Content-Typeapplication/json

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

[
    {
        "agile_approval_enabled": true,
        "attachments": [],
        "author": {
            "id": 1,
            "display_name": "user-display-name",
            "email": "[email protected]",
            "username": "username",
            "url": "/user/1/"
        },
        "body": "<p>An article without children</p>",
        "children": [],
        "custom_fields": [],
        "custom_templates": [],
        "editors": [
            {
                "id": 1,
                "display_name": "user-display-name",
                "email": "[email protected]",
                "username": "username",
                "url": "/user/1/"
            }
        ],
        "has_children": false,
        "id": 18,
        "private": false,
        "title": "Articles API",
        "ts_updated": "2018-01-09T02:25:39.452678Z",
        "ts_created": "2017-12-05T23:24:04.000907Z",
        "url": "/article/18/articles-api"
    },
    {
        "agile_approval_enabled": true,
        "attachments": [],
        "author": {
            "id": 1,
            "display_name": "user-display-name",
            "email": "[email protected]",
            "username": "username",
            "url": "/user/1/"
        },
        "body": "<p>Another article without children!</p>",
        "children": [],
        "custom_fields": [],
        "custom_templates": [],
        "editors": [
            {
                "id": 1,
                "display_name": "user-display-name",
                "email": "[email protected]",
                "username": "username",
                "url": "/user/1/"
            }
        ],
        "has_children": false,
        "id": 5,
        "private": false,
        "title": "Next article",
        "ts_updated": "2018-01-09T02:25:39.452678Z",
        "ts_created": "2017-12-05T23:24:04.000907Z",
        "url": "/article/5/next-article"
    }
]

Update an article

This API is used to update title, body, private, custom_templates and children of articles that are active. Deleted articles cannot be updated.

NOTE: Children can only be added and not removed, as of now.

URL

PUT /integration/v1/article/**<article_id>**/

Replace <article_id> with the unique identifier of an article.

Data Parameters

NameRequiredDescription
titleYesThe title of the article.
bodyYesThe body of the article.
privateNoIf the article is private.
agile_approval_enabledNotrue when Agile Approval is enabled on the article. For new Articles, this defaults to false.
custom_templatesNoList of updated custom-template Ids.
Example: [1,2,3]
childrenNoList of new children (can be article or table), to be added to the article.
Example: [{"id": 1, "otype": "Table"}, {"id": 3, "otype": "Article"}]

Sample Request Body

{
    "body": "Updated article body",
    "title": "Articles API",
    "private": true,
    "agile_approval_enabled": true,
    "custom_templates": [1,4],
    "children": [{"id": 3, "otype": "Article"}]
}

Headers

HTTP HeaderValue
Token<your_token>
Content-Typeapplication/json

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

{
    "agile_approval_enabled": true,
    "attachments": [],
    "author": {
        "id": 1,
        "display_name": "user-display-name",
        "email": "[email protected]",
        "username": "username",
        "url": "/user/1/"
    },
    "body": "<p>Updated article body!</p>",
     "children": [
        {
            "id": 1,
            "otype": "article",
            "title": "Database information",
            "url": "/article/1/database-information"
        },
        {
            "id": 3,
            "otype": "table",
            "name": "table3",
            "title": "Sales information",
            "url": "/table/3/"
        },
        {
            "id": 3,
            "otype": "article",
            "title": "Company policies",
            "url": "/article/3/company-policies"
        },
    ],
    "custom_fields": [],
    "custom_templates": [
        {
            "id": 1,
            "title": "Business Glossary template"
        },
        {
            "id": 4,
            "title": "Additional Custom Fields"
        }
    ],
    "editors": [
        {
            "id": 1,
            "display_name": "user-display-name",
            "email": "[email protected]",
            "username": "username",
            "url": "/user/1/"
        }
    ],
    "has_children": false,
    "id": 18,
    "private": true,
    "title": "Articles API",
    "ts_updated": "2018-01-09T02:25:39.452678Z",
    "ts_created": "2017-12-05T23:24:04.000907Z",
    "url": "/article/18/articles-api"
}

Delete an article

This API is used to delete an existing article.

NOTE: You can delete an article only if you are an admin-user or you are the author of that article.

URL

DELETE /integration/v1/article/**<article_id>**/

Replace <article_id> with the unique identifier of an article.

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

Resurrect an article

This API is used to restore a deleted article.

NOTE: You can resurrect an article only if you are an admin-user or you are the author of that article.

URL

POST /integration/v1/article/**<article_id>**/resurrect/

Replace <article_id> with the unique identifier of an article.

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

{
    "agile_approval_enabled": false,
    "attachments": [],
    "author": {
        "id": 1,
        "display_name": "user-display-name",
        "email": "[email protected]",
        "username": "username",
        "url": "/user/1/"
    },
    "body": "<p>Updated article body!</p>",
     "children": [],
    "custom_fields": [],
    "custom_templates": [
        {
            "id": 1,
            "title": "Business Glossary template"
        }
    ],
    "editors": [
        {
            "id": 1,
            "display_name": "user-display-name",
            "email": "[email protected]",
            "username": "username",
            "url": "/user/1/"
        }
    ],
    "has_children": false,
    "id": 18,
    "private": true,
    "title": "Articles API",
    "ts_updated": "2018-01-09T02:25:39.452678Z",
    "ts_created": "2017-12-05T23:24:04.000907Z",
    "url": "/article/18/articles-api"
}

Error Response

Invalid Token

Status: 403 Forbidden

Body

{
   "detail": "Invalid API token."
}

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/v1/article"

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

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

# Add an article
curl -X POST "${BASE_URL}/" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" -d '{
    "title" : "Title of the article",
    "body": "Body of the article."
}'

# Add an article with custom templates
curl -X POST "${BASE_URL}/" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" -d '{
    "title" : "Articles API",
    "body": "Adding articles with custom templates"
    "custom_templates": [1,2]
}'

# Update an article
curl -X PUT "${BASE_URL}/1/" -H 'content-type: application/json' -H "TOKEN: ${API_TOKEN}" -d '{
    "title" : "Title of the article",
    "body": "Body of the article.",
    "private": "true"
}'

# Delete an article
curl -X DELETE "${BASE_URL}/1/" -H "TOKEN: ${API_TOKEN}"

# Resurrect an article
curl -X POST "${BASE_URL}/1/resurrect/" -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 articles
response = requests.get('https://alation.yourcompany.com/integration/v1/article/', headers=headers)
articles = json.loads(response.text)
for article in articles:
    print "ID: %s, Title: %s" % (article['id'], article['title'])

# Get details of a particular article
response = requests.get('https://alation.yourcompany.com/integration/v1/article/1/', headers=headers)
article = json.loads(response.text)
print "ID: %s, Title: %s" % (article['id'], article['title'])

data = {
    "title" : "Articles API",
    "body": "Getting started with the Articles API"
}

# Add an article
response = requests.post('https://alation.yourcompany.com/integration/v1/article/', json=data, headers=headers)
article = json.loads(response.text)
print "ID: %s, Title: %s" % (article['id'], article['title'])

# Add an article with custom templates
data = {
    "title" : "Articles API",
    "body": "Adding articles with custom templates",
    "custom_templates": [1,2]
}

response = requests.post('https://alation.yourcompany.com/integration/v1/article/', json=data, headers=headers)
article = json.loads(response.text)
print "ID: %s, Title: %s" % (article['id'], article['title'])

# Update an article
data = {
    "title" : "Articles API",
    "body": "Getting started with the Articles API",
    "private": "true"
}
response = requests.put('https://alation.yourcompany.com/integration/v1/article/1/', json=data, headers=headers)
article = json.loads(response.text)
print "ID: %s, Title: %s" % (article['id'], article['title'])

# Delete an article
response = requests.delete('https://alation.yourcompany.com/integration/v1/article/1/', headers=headers)
print "Status Code: %s" % (response.status_code)

# Resurrect an article
response = requests.post('https://alation.yourcompany.com/integration/v1/article/1/resurrect/', headers=headers)
print "Status Code: %s" % (response.status_code)