API Catalog

Core Capabilities

• API Discovery - Search the API catalog by task, category, or service name
• OpenAPI Parsing - Fetch and parse OpenAPI/Swagger specs from URLs
• Documentation Access - Fetch and parse API documentation from source URLs
• Code Generation - Generate implementation code for API integration
• API Comparison - Compare multiple API options for the same use case
• Spec Storage - Store and manage local OpenAPI specs for quick reference

When to Use

• When you need API recommendations for a specific task
• When integrating with external services or third-party APIs
• When asking about available APIs for payment processing, messaging, etc.
• When needing implementation examples for API integration
• When comparing different API options (REST, GraphQL, gRPC)

OpenAPI/Swagger Support

OpenAPI specifications are machine-readable YAML/JSON files that define:

• Endpoints - Available paths and HTTP methods
• Parameters - Query, path, header, and body parameters
• Schemas - Request/response data structures
• Authentication - Security schemes (API key, OAuth2, etc.)
• Examples - Sample requests and responses

Workflow: Parsing OpenAPI from URL

1. Fetch the spec - Use WebFetch to retrieve the OpenAPI YAML/JSON from the URL
2. Parse key sections - Extract info, servers, paths, components/schemas, securitySchemes
3. Extract endpoint details - HTTP method, path parameters, query parameters, request body, responses
4. Generate documentation summary - Present overview, endpoints, authentication, data models

Code Generation Example

When generating implementation code from an OpenAPI spec:

interface PolicyCreate {
  policyNumber: string;
  holderName: string;
  coverageType: 'basic' | 'premium' | 'comprehensive';
  startDate: string;
}

async function createPolicy(
  data: PolicyCreate,
  token: string
): Promise<Policy> {
  const response = await fetch('https://api.example.io/api/v1/policies', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

API Types Supported

• REST APIs - HTTP-based, JSON/XML, standard methods (GET, POST, etc.)
• GraphQL - Query language, single endpoint, flexible data fetching
• gRPC - Protocol buffers, binary protocol, high performance
• SaaS APIs - Third-party services (Stripe, Twilio, AWS, etc.)

Key Principles

• OpenAPI first - Always check for OpenAPI spec before manual parsing
• Structured data - Prefer machine-readable specs for accuracy
• Working code - Generate complete, typed, runnable implementations
• Full context - Include authentication, error handling, types
• Keep updated - Store and version important specs locally