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:

Use SSH to connect to your Alation server.
Enter the Alation shell.
sudo /etc/init.d/alation shell
Using alation_conf, set the flag alation.feature_flags.enable_api_resource to True.
alation_conf alation.feature_flags.enable_api_resource -s True
Restart the Alation server to apply the change.
alation_action restart_alation
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:
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.

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		A folder storing API resources
API resource object		The API resource catalog object stored as a bundle of its URI or URL, API method, and input and output schemas.
API resource field		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 Applying Custom Fields to Templates

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:

Common Actions on API Resource Objects¶

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

Add Tags
Add or Change the Description
Deprecate, Warn, Endorse
Star and Watch
Start a Conversation

Add Tags¶

To add a tag to the page:

Find the Tags section and hover over it to reveal the Add icon.
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:

Mouseover the Description section of the page to reveal the Edit icon.
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:

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:

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.

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.