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

Name	Required	Description
title	Yes	Title of the article.
body	Yes	Body of the article.
private	No	Is the article private? (By default, it is public)
custom_templates	No	List of custom-template IDs, which can be obtained from CustomTemplates API call.(Custom Template) Example: `[1,2]`
children	No	List of children (can be article or table) Example: `[{"id": 1, "otype": "Table"}, {"id": 3, "otype": "Article"}]`
agile_approval_enabled	No	`true` 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 Header	Value
Token	<your_token>
Content-Type	application/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:

Name	Description
id	Unique identifier of the article
title	Title of the article
ts_updated	Timestamp when the article is last updated
ts_created	Timestamp when the article is created
agile_approval_enabled	`true` when Agile Approval is enabled on the article. For new Articles, this defaults to `false`.
attachments	List of attachments of the article
author	Author details like id, username, display_name, email and url
body	Body of the article
children	Children of the article, can be tables or articles
custom_fields	non empty custom_fields of the article: Custom Fields Format API
custom_templates	List of custom_templates assigned to the article
editors	List of all the contributors of the article, contains id, username, display_name, email and url
has_children	Boolean to indicate if article has children
private	Boolean to indicate if the article is private
url	URL 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 Header	Value
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

Name	Required	Data Type	Description
title	No	string	Filter articles with this title. Example: `/integration/v1/article/?title=Articles API`
title__icontains	No	string	Filter articles whose titles contain this word. Example: `/integration/v1/article/?title__icontains=sales`
has_children	No	boolean	Filter articles with/without children. Example: `/integration/v1/article/?has_children=True`
custom_field_templates	No	list of custom-template IDs	Filter articles with atleast one custom_template belonging to this list. Example: `/integration/v1/article/?custom_field_templates=[1,2]`
values	No	comma separated list of field_names	Fields 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

Name	Required	Description
otype	Yes	Otype of the object, whose relevant articles are desired.
oid	Yes	Oid of the object, whose relevant articles are desired.
include_shared	No	Boolean 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 Header	Value
Token	<your_token>
Content-Type	application/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

Name	Required	Description
title	Yes	The title of the article.
body	Yes	The body of the article.
private	No	If the article is private.
agile_approval_enabled	No	`true` when Agile Approval is enabled on the article. For new Articles, this defaults to `false`.
custom_templates	No	List of updated custom-template Ids. Example: `[1,2,3]`
children	No	List 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 Header	Value
Token	<your_token>
Content-Type	application/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 Header	Value
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 Header	Value
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)