API Catalog

Ai & Modern Apis Jan 14, 2026 YAML
documentation developer-experience discovery portal

Definition

An API Catalog is a curated, developer-facing directory of available APIs designed to help internal developers, partners, or external consumers discover and integrate with APIs quickly. Unlike an API Inventory (which tracks all APIs for governance), a Catalog showcases published APIs with rich documentation, usage examples, and onboarding guides.

Think of the Catalog as a product showcase: it presents APIs as products that developers want to use, complete with “getting started” guides, code samples, authentication instructions, and interactive testing tools. The goal is developer experience (DX), not compliance—making it easy to find, understand, and integrate with APIs.

A good API Catalog answers: “What can I build with these APIs?” while an Inventory answers “What APIs exist and who owns them?” Both are essential but serve different purposes.

Example

Stripe’s API Catalog:

Stripe’s public API reference (https://stripe.com/docs/api) is an exemplary API Catalog:

  • Searchable: Type “payment” and find relevant endpoints instantly
  • Interactive: Try API calls directly from documentation with real API keys
  • Code examples: Every endpoint shows curl, Python, Ruby, Node.js examples
  • Organized by use case: “Accept a payment”, “Create a customer”, “Issue a refund”
  • Versioned: See documentation for current version + historical versions

Twilio’s API Catalog:

Twilio organizes their catalog by product (SMS, Voice, Video), making it easy to find relevant APIs for your use case. Each API includes:

  • Quickstart guides (“Send your first SMS in 5 minutes”)
  • SDKs for 7+ languages
  • Rate limits and pricing information
  • Sample applications you can deploy immediately

Internal Catalog Example:

A company’s internal developer portal might catalog:

  • Customer API: Manage customer profiles and preferences
  • Orders API: Create and track orders
  • Inventory API: Check product availability
  • Payments API: Process payments and refunds

Each entry includes: endpoints, authentication method, rate limits, example requests/responses, and contact information for the owning team.

Analogy

The Restaurant Menu: An API Catalog is like a restaurant menu. The menu doesn’t list everything the kitchen can make (that’s the inventory)—it shows what’s available to customers right now, with descriptions, prices, and pictures. The menu is designed for customers to make decisions quickly (“I’ll have the pasta”). Similarly, an API Catalog shows developers what’s available and helps them choose the right API for their needs.

The Product Showroom: IKEA doesn’t show you their entire warehouse inventory—they create showrooms displaying finished room setups so you can imagine how products work together. An API Catalog is this showroom: curated, organized, and designed for discovery, not comprehensive audit.

Code Example

API Catalog Entry (YAML):


# catalog-entry.yaml
# Example catalog entry for Customer API

api:
  id: "customers-api-v2"
  name: "Customer Management API"
  version: "2.1.0"
  status: "stable"
  tagline: "Manage customer profiles, preferences, and account details"

  # Developer-focused information
  getting_started:
    quickstart_url: "https://docs.company.com/quickstart/customers"
    estimated_time: "10 minutes"
    prerequisites:
      - "OAuth2 client credentials"
      - "Basic understanding of REST APIs"

  # API Details
  base_url: "https://api.company.com/v2/customers"
  authentication:
    - type: "oauth2"
      scopes: ["customers:read", "customers:write"]
    - type: "api_key"
      note: "Deprecated, use OAuth2 for new integrations"

  rate_limits:
    - tier: "free"
      limit: "100 requests/hour"
    - tier: "paid"
      limit: "10,000 requests/hour"

  # Documentation
  documentation:
    overview: "https://docs.company.com/api/customers"
    openapi_spec: "https://api.company.com/openapi/customers-v2.yaml"
    interactive_docs: "https://api.company.com/swagger-ui/customers"
    changelog: "https://docs.company.com/changelog/customers"

  # Code Examples
  code_samples:
    - language: "curl"
      example: |
        curl -X GET "https://api.company.com/v2/customers/cust_123" \
          -H "Authorization: Bearer YOUR_TOKEN"

    - language: "javascript"
      example: |
        const customer = await fetch('https://api.company.com/v2/customers/cust_123', {
          headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
        }).then(r => r.json());

    - language: "python"
      example: |
        import requests
        response = requests.get(
          'https://api.company.com/v2/customers/cust_123',
          headers={'Authorization': 'Bearer YOUR_TOKEN'}
        )
        customer = response.json()

  # Support
  support:
    team: "Customer Platform Team"
    email: "[email protected]"
    slack: "#api-customers"
    oncall: "pagerduty://customer-platform"

  # Common Use Cases
  use_cases:
    - title: "Create a new customer account"
      endpoint: "POST /v2/customers"
      doc_link: "https://docs.company.com/tutorials/create-customer"

    - title: "Update customer preferences"
      endpoint: "PATCH /v2/customers/{id}/preferences"
      doc_link: "https://docs.company.com/tutorials/customer-preferences"

    - title: "Search customers by email"
      endpoint: "GET /v2/customers?email={email}"
      doc_link: "https://docs.company.com/tutorials/search-customers"

  # Related APIs
  related_apis:
    - "orders-api-v2"
    - "payments-api-v2"
    - "notifications-api-v1"

Diagram

graph TB
    A[API Catalog] --> B[Developer Portal UI]
    A --> C[Search & Discovery]
    A --> D[Documentation]
    A --> E[Interactive Tools]

    B --> B1[Categorized Listings]
    B --> B2[Popular APIs]
    B --> B3[Recently Updated]

    C --> C1[Full-Text Search]
    C --> C2[Tag-Based Filtering]
    C --> C3[Use-Case Browse]

    D --> D1[Getting Started Guides]
    D --> D2[API Reference]
    D --> D3[Code Examples]
    D --> D4[Tutorials]

    E --> E1[Interactive API Explorer]
    E --> E2[Try It Now]
    E --> E3[Code Generators]

    F[Target Audience] --> F1[Internal Developers]
    F --> F2[Partner Integrators]
    F --> F3[External Consumers]

    F1 --> B
    F2 --> B
    F3 --> B

    style A fill:#bbdefb
    style B fill:#c8e6c9
    style D fill:#fff9c4
    style E fill:#e1bee7

Catalog vs Inventory

AspectAPI CatalogAPI Inventory
PurposeDeveloper experienceGovernance & compliance
AudienceDevelopers, partnersSecurity, architects, compliance
ContentPublished, stable APIsAll APIs (including Shadow, Zombie)
CurationHighly curatedComprehensive (no curation)
MetadataUsage examples, tutorialsOwner, status, compliance tags
Update frequencyWhen APIs changeReal-time (automated discovery)
Focus“How do I use this?”“What exists and who owns it?”

Both are essential: Inventory for governance, Catalog for developer productivity.

Essential Catalog Features

1. Search & Discovery

  • Full-text search across API names, descriptions, and endpoints
  • Tag-based filtering (“show me all payment APIs”)
  • Use-case organization (“How do I send an email?”)

2. Rich Documentation

  • Getting started guide (5-10 minute quickstart)
  • Complete API reference (all endpoints)
  • Authentication instructions with examples
  • Rate limits and error handling

3. Interactive Testing

  • “Try it now” functionality (Swagger UI, Stoplight, Postman)
  • Pre-filled example requests
  • Test against sandbox environments

4. Code Samples

  • Examples in 3-5 languages (curl, JavaScript, Python, Java, etc.)
  • Copy-paste ready snippets
  • Complete SDK documentation if available

5. Versioning

  • Current version clearly marked
  • Historical version documentation available
  • Migration guides between versions

6. Support Information

  • Owning team contact (email, Slack, PagerDuty)
  • Known issues and status page
  • Changelog and release notes

Common Mistakes

Mistake 1: Catalog = Swagger/OpenAPI spec An OpenAPI spec is a reference, not a catalog. Developers need tutorials, examples, and use-case guidance, not just endpoint definitions.

Mistake 2: Including internal/deprecated APIs A Catalog should be curated. Don’t list every API—only ones you want developers to use. Deprecated APIs get a “Legacy” section with migration guides.

Mistake 3: No search functionality If developers can’t find APIs quickly, they’ll build duplicates. Search must be fast and comprehensive.

Mistake 4: Documentation without examples “This endpoint accepts a JSON body” is useless. Show an actual example: {"name": "John Doe", "email": "[email protected]"}.

Mistake 5: Outdated information If your Catalog says the API requires an API key but it’s been migrated to OAuth2, developers will fail to authenticate. Keep Catalog in sync with reality.

Best Practices

  1. Update automatically: Generate Catalog from OpenAPI specs + metadata, don’t maintain manually
  2. Organize by use case: “How to send notifications” is better than alphabetical API list
  3. Highlight popular APIs: Show “Most used” or “Recently updated” sections
  4. Provide sandboxes: Let developers test without affecting production
  5. Include rate limits: Developers need to know quotas upfront
  6. Link to support: Every API should have a clear support channel
  7. Measure usage: Track which APIs are most searched, which docs are most viewed

Tools for API Catalogs

Open Source:

Backstage (Spotify)

  • Developer portal with API plugin
  • Customizable, extensible
  • Integration with CI/CD pipelines

Swagger UI

  • Interactive API documentation
  • Automatically generates from OpenAPI specs
  • Try-it-now functionality

Stoplight

  • API documentation platform
  • Mock servers and testing
  • Collaborative editing

Commercial:

Postman Workspaces

  • Team collaboration on APIs
  • Private API catalog
  • Testing and monitoring

SwaggerHub

  • API design and documentation
  • Team collaboration
  • Auto-generated client SDKs

Azure API Center

  • Centralized catalog for Azure APIs
  • Discovery and governance
  • Integration with Azure API Management

ReadMe

  • Developer documentation platform
  • Interactive API explorer
  • Metrics and analytics

Implementation Tips

Phase 1: Minimal Catalog (Week 1)

  • List 10-20 most important APIs
  • Include: name, description, OpenAPI spec link, owner contact
  • Deploy to internal wiki or Confluence

Phase 2: Rich Catalog (Month 1)

  • Add getting started guides for top 5 APIs
  • Include code examples (curl, JavaScript, Python)
  • Implement search functionality

Phase 3: Interactive Catalog (Month 2-3)

  • Deploy Swagger UI or Stoplight
  • Add try-it-now functionality
  • Create sandbox environments

Phase 4: Polished Catalog (Month 3+)

  • Use-case organization
  • Video tutorials for complex APIs
  • Metrics: track search queries, popular APIs

Example: Stripe’s Developer Experience

Why Stripe’s Catalog excels:

  1. Frictionless onboarding: Create account → Get API key → Make first request in <5 minutes
  2. Interactive testing: Try every endpoint directly from docs
  3. Language-specific docs: Toggle between curl, Python, Ruby, Node.js, PHP, Go, .NET
  4. Real-time testing: Test with real keys against test mode
  5. Comprehensive examples: Not just “create a payment” but “create a payment with 3D Secure authentication”
  6. Status dashboard: Real-time API health monitoring

Result: Developers love Stripe’s APIs because of the documentation. The Catalog is a competitive advantage.

Further Reading

API Documentation Best Practices:

Related Concepts:

Tools Mentioned:

Related Terms: