API Resource Cataloging

Alation provides the ability to add API resources to the catalog and document them alongside other catalog objects. Adding API resources to Alation can help collect information on useful API endpoints in one place, organize them into a convenient-to-use folder structure, describe their benefits or caveats using catalog fields, and make that information accessible to all catalog users. With API resources added to the catalog, analysts can easily discover the APIs available to them and understand how they can be leveraged to get data sets.

The API resource object is a segment of data at a specific server endpoint that is available to analysts and that can be stored in Alation as a structured metadata object.

Enable API Resource Cataloging

To enable API resource cataloging:

  1. Use SSH to connect to your Alation server.

  2. Enter the Alation shell.

    sudo /etc/init.d/alation shell
    
  3. Using alation_conf, set the flag alation.feature_flags.enable_api_resource to True.

    alation_conf alation.feature_flags.enable_api_resource -s True
    
  4. Restart the Alation server to apply the change.

    alation_action restart_alation
    
  5. Exit the Alation shell.

    exit
    

Add API Resource Objects to the Catalog

API resources can be added to the catalog using the API Resource API that allows you to add, update, delete, and retrieve API resource objects.

Find API Resources in the Catalog

To find API resources in the catalog:

  • Use Alation Search. If you know the title of the API resource you are looking for, start typing it. The search results update dynamically to show the objects that fit your search query.

  • To browse available API resources, click the More Types… filter on the Search page and in the list of object types, click any of the available API resource object types:

    ../../_images/API_Resources_01.png
  • To view the catalog page for a specific API resource, click its title in the Search results.

  • Click Apps on the main toolbar and then click Sources. On the Sources page > Browse Sources tab, click API Resources to open the list of API resources currently available in the catalog. To view a specific API resource folder, click its name in this list.

    ../../_images/API_Resources_02.png

API Resource Catalog Page Templates

Definitions

API resource is a collective term that can denote API resource objects, their containers (folders), and API request components (fields). Cataloged API resources are stored in folders. Each resource can nest components down to the field level. The table below explains the concept of API resources.

Term

Icon

Definition

API resource folder

../../_images/API_Resources04.png

A folder storing API resources

API resource object

../../_images/API_Resources03.png

The API resource catalog object stored as a bundle of its URI or URL, API method, and input and output schemas.

API resource field

../../_images/API_Resources05.png ../../_images/API_Resources06.png ../../_images/API_Resources07.png

An API resource component that stores the key of the schema and is defined by the data type. In the user interface, Alation displays objects and arrays as expandable nodes. Fields are the lowest nested level objects. Arrays drilling down to the field level.

Page Templates and Actions

Folders, resource objects, and fields each have their own catalog page that can be customized to document the purpose of the API resource and recommendations for its users. These pages are built on customizable templates and have both common elements and those specific to each object.

API Resource Folder Page

The API resource folder page includes the following elements:

Page Element

Description

Title

The title field, non-editable

Description

Description, editable

Resources Table

Can include both nested API resource folders and API resources.

  • Name—Name of the API folder or resource

  • URL—Endpoint of the cataloged API resource that displays the API method and the resource URL

  • Type—Type of the API resource object (folder or resource)

Tags

Tags on the object

Relevant Articles

List of articles mentioning the object

Custom Fields

It is possible to add more custom fields to a catalog page. For details on custom fields and how to add them, refer to About Templates and Fields.

API Resource Page

The API resource page includes the following elements:

Page Element

Description

Title

The title field, non-editable

Overview tab

  • URL—Endpoint of the cataloged API resource that displays the API method and the resource URL

  • Description—Description, editable

Properties

  • Request Type—Method of the API endpoint

  • Response Type—Expected response type

Tags

Tags on the object

Relevant Articles

List of articles mentioning the object

Input tab

Table representation of the input schema for the API resource, including:

  • Key

  • Type

  • Examples

  • Required

  • Title

  • Description

The Key names are clickable and navigate to either their nested level (for objects and arrays) or their property page (other data types).

Output tab

Table representation of the output schema for the API resource, including:

  • Key

  • Type

  • Examples

  • Title

  • Description

The Key names are clickable and navigate to either to their nested level (for objects and arrays) or to their property page (other data types).

Custom fields

It is possible to add more information fields to the catalog page by adding custom fields.

API Resource Field Page

The API resource field page includes the following elements:

Page Element

Description

Title

The source title, non-editable. It is also possible to add another custom title to this object.

Description

Description, editable

Sample Values

Example of the field value

Schema

Available for the API resource fields that are objects or arrays. It’s a table representation of the object or array schema, including:

  • Key—Can be expanded to the next nested field level

  • Type—Data type

  • Examples

  • Title

  • Description

Properties

  • Type—Data type

  • API Input/Output (present if this field is found in the input or output schema

Tags

Tags on the object

Relevant Articles

List of articles mentioning the object

Custom Fields

It is possible to add more information fields to the catalog page by adding custom fields.

Example API Resource object page:

../../_images/API_Resources08.png

Common Actions on API Resource Objects

On any of the API resource catalog pages, you can:

Add Tags

To add a tag to the page:

  1. Find the Tags section and hover over it to reveal the Add icon.

  2. Click Add to open the list of Tags, find a tag to add, and click it in the list. The selected Tag will be added o the page.

For more information on tags, see Tags.

Add or Change the Description

To change the Description:

  1. Mouseover the Description section of the page to reveal the Edit icon.

  2. Click Edit, add or change the Description, and click Save.

Deprecate, Warn, Endorse

To label the object as Deprecated, add a warning about it, or to endorse it, click the corresponding Traffic Light icon in the upper-left corner next to the title. For more information, see Add Endorsements, Warnings, and Deprecation Messages to Data.

Star and Watch

To star a catalog object, click the star icon on the upper right of the catalog page:

../../_images/UI_StarIcon.png

Starring an object adds it to the list of your favorites in Alation. To remove it from your favorites list, click the star again. An orange star means the object is currently in the favorites list, while gray means starring is not applied.

To watch a catalog object, click the watch icon on the upper right of the catalog page:

../../_images/UI_WatchIcon.png

Watching signs you up for email notifications. You will get notified whenever another user makes a change to the page. To stop watching, click the watch icon again. Orange means watching is toggled on, while the gray watch icon means it is off.

Starring and watching Alation objects makes them easy to find and navigate to in Alation. You can quickly find the list of objects you have starred or are watching or by clicking the star or watch icons in the Filters area of the full-page search page.

../../_images/Gloss_star.png

Start a Conversation

You can discuss a catalog page in a conversation. For more information, see Conversations.

Customize API Resource Object Pages

To customize the catalog pages of API resources, you can add more custom fields that will reflect relevant information. For details on custom fields, see Customize Your Data Catalog.