API Labeling and Categorization

Overview | Quick Start | How It Works | Use Cases | Best Practices | FAQs | Troubleshooting

Overview

API Labeling and Categorization enables you to organize, classify, and filter your APIs using customizable metadata tags. This feature allows you to create a structured taxonomy for your API landscape, making it easier to search, filter, and apply governance policies based on business context, technical characteristics, or organizational ownership.

Key Benefits

• Enables structured organization of APIs by business domain, criticality, and other dimensions
• Facilitates efficient search and filtering of APIs in large inventories
• Provides consistent metadata across APIs from different sources
• Supports governance policy application based on API characteristics (Governance Policy feature is coming soon)
• Enables reporting and analytics based on business context (Reporting feature is coming soon)

Quick Start

In this tutorial, we’ll explore how to use API labeling to categorize and filter APIs in your organization’s API Repository.

Prerequisites

• Access to the Tyk Governance Hub
• Governance Admin access for creating new label definitions (Note: only admin access is available at the moment)

Step-by-Step

1. Access the API Repository

   Navigate to the API Repository section in your Tyk Governance dashboard.

2. Explore default labels

   Tyk Governance comes with pre-configured default labels such as “Business Domain” and “API Criticality”.

3. Apply labels to APIs

   Select an API and click “Edit” to apply or modify labels:

   • Set “Business Domain” to an appropriate value (e.g., “Finance”, “Customer”, “Product”)
   • Assign “API Criticality” based on the API’s importance (Tier 1 for mission-critical, Tier 2 for important, Tier 3 for non-critical)
   • Add any custom labels that have been defined by your Governance Admin

4. Filter APIs using labels

   Use the search and filter functionality to find APIs based on their labels:

   • Filter to show only Tier 1 APIs
   • Search for APIs in a specific business domain
   • Combine multiple label filters for precise results

5. Create a custom label (Admin only)

   Governance Admin users can create custom labels programmatically using the API:

   Example using cURL:

	curl -X POST https://your-governancel-instance.tyk.io/api/labels/ \
	-H "Content-Type: application/json" \
	-H "X-API-Key: YOUR_ADMIN_TOKEN" \
	-d '{
		"name": "compliance",
		"values": ["PCI-DSS", "GDPR", "HIPAA"]
	}'

A successful request will return a 200 OK status code and the newly created label object:

	{
	"id": "64a1b2c3d4e5f6a7b8c9d0e1",
	"name": "compliance",
	"values": ["PCI-DSS", "GDPR", "HIPAA"]
	}

Notes:

• The name field is required and must be unique
• The values field is optional. If provided, it defines the allowed values for this label
• If values is empty, the label will accept any value (free text)
• Only users with admin privileges can create labels
• Once created, labels can be applied to APIs using the /api/{api-id}/labels endpoint
• After creating a custom label, it will be available for selection when labeling APIs, either through the UI or via the API labeling endpoints.

Validation

• Labeled APIs will display their labels in the API details view
• Filtering by labels will show only matching APIs
• New custom labels will be available for application to APIs

How It Works

API Labeling and Categorization works through a flexible key-value metadata system that allows both structured and free-form classification of APIs.

Labeling System Architecture

1. Bootstrap Default Labels: During initial setup, Tyk Governance creates default label definitions such as “Business Domain” and “API Criticality”.

2. Label Definition: Each label has:

   • A unique key (e.g., “business_domain”)
   • A display name (e.g., “Business Domain”)
   • A value type (free text or predefined values)
   • Optional predefined values (e.g., “Finance”, “HR”, “Operations”)

3. Label Application: Labels are applied to APIs as key-value pairs:

   • Key: The label identifier (e.g., “business_domain”)
   • Value: The specific value for this API (e.g., “Finance”)

4. Label Storage: Labels are stored as metadata with each API in the repository database.

5. Search and Filter: Tyk Governance indexes labels to enable efficient filtering and searching.

Use Cases

Governance Policy Application

Apply different governance rules based on API criticality tiers. For example, Tier 1 (mission-critical) APIs might require stricter security controls, more thorough documentation, and formal change management processes.

Compliance Management

Tag APIs with relevant compliance requirements (PCI-DSS, GDPR, HIPAA) to ensure appropriate controls are applied and to facilitate compliance reporting and audits.

Team Ownership and Responsibility

Label APIs by owning team or department to clarify responsibility for maintenance, support, and governance compliance.

API Lifecycle Management

Use labels to indicate lifecycle stage (Development, Testing, Production, Deprecated) to manage API transitions and communicate status to consumers.

Best Practices and Recommendations

• Establish a clear labeling taxonomy before implementing across your organization
• Keep predefined value lists manageable – too many options create confusion and inconsistency
• Use hierarchical naming for related labels (e.g., security.authentication.method, security.data.classification)
• Document the meaning and intended use of each label for consistent application
• Assign label management responsibility to a specific role or team to maintain consistency
• Review and update labels periodically to ensure they remain relevant as your API landscape evolves
• Include label application in API onboarding workflows to ensure consistent metadata from the start
• Use consistent labeling conventions across all APIs to facilitate effective filtering and governance
• Combine multiple labels in filters for more precise API discovery
• Use criticality and domain labels as the foundation of your governance strategy

FAQs

Troubleshooting