API Resource Cataloging¶

Available from version V R2 (5.6.x) - Beta

Alation provides the ability to add API resources to the Catalog and document them alongside the 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 datasets.

The API Resource object in Alation is a “segment” of data at a server endpoint that is available to analysts and that is stored in Alation as a structured metadata object.

Important

This feature requires pre-configuration.

Enabling API Resource Cataloging¶

To enable API Resource cataloging,

SSH 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

Adding API Resource Objects to the Catalog¶

API Resources can be added to the Catalog using the API Resource API.

The API Resource API allows you to add, update, delete, and retrieve existing API Resources. For the details on this API, see the corresponding API documentation: API Resource API.

Locating API Resources in the Catalog¶

To find API Resources in the catalog:

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

To browse the 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. Alation will search for objects in this set.

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¶

Cataloged API Resources can be stored in folders. Each Resource can nest components down to the field level. Alation uses the following terms to document API Resources:

Term	Icon	Definition
API Resource		A collective term denoting API Resources, their containers (folders), and API request components (arrays, objects, fields).
API Resource Folder		A folder storing API Resources
API Resource Object		The actual cataloged resource 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 UI, Alation differentiates objects and arrays as expandable nodes. Fields are the lowest nested level objects and arrays can be drilled down to the field level.

Page Templates and Actions¶

Folders, Resources, and Fields each have their own Catalog pages 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 in Alation includes the following elements:

Page Element	Description
Title	The title, non-editable
Description	Description, editable
Resources Table	Can include both nested API Resource folders and API Resources. Name the name of the API Folder or Resource URL the endpoint of the cataloged API Resource that displays its method and the resource URL Type type of API Resource Object (Folder or Resource)
Tags	Tags for this object
Relevant Articles	List of articles mentioning this object
Custom fields	It is possible to add more custom fields to the catalog page. For details on custom fields and how to add them, see Applying Custom Fields to Templates

API Resource Page¶

The API Resource page in Alation includes the following elements:

Page Element	Description
Title	The title, non-editable
Overview tab	URL The endpoint of the cataloged API Resource that displays its method and the resource URL Description: description, editable
Properties	Request Type the method of this API call Response Type the expected response type
Tags	Tags for this object
Relevant Articles	List of articles mentioning this object
Input tab	Table representation of the Input schema for the API Resource that includes: Key Type Examples Required Title Description The Key names are clickable and lead either to their nested level (for objects and arrays) or to their property page (for other data types).
Output tab	Table representation of the Output schema for the API Resource that includes: Key Type Examples Title Description The Key names are clickable and lead either to their nested level (for objects and arrays) or to their property page (for 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 in Alation 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	Available for the API Resource Fields. It gives an example of the field value.
Schema	Available for the API Resource fields that are Objects or Arrays. It is a table representation of the object or array schema that includes: Key - drillable to the next nested field level Type - data type Examples Title Description
Properties	Type data type API Input/Output if this field is found in the Input or Output schema
Tags	Tags for this object
Relevant Articles	List of articles mentioning this 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 these Catalog pages, you can:

Add a Tag¶

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 How to Use 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¶

You can star a Catalog page. This adds it to your favorites to quickly find it using Search.

You can start watching a page. For more information, see What Does Watching Mean.

Conversations¶

You can discuss the page in a Conversation. For more information, see Conversations.

Customizing the API Resource Object Pages¶

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