Openapi Endpoint Filtering

OpenAPI Endpoint Filtering & Route Pruning Protocol

Overview

When generating an API integration client or debugging a REST webhook, agents often ingest the entire openapi.json or swagger.yaml specification file.

In enterprise platforms (Stripe, GitHub, AWS, Kubernetes), complete OpenAPI specifications span 15,000 to 60,000 lines of JSON (consuming 80,000 to 250,000 tokens). Ingesting the full spec crashes context windows and costs dollars per query - even if the developer only wants to integrate a single endpoint (POST /v1/refunds).

The OpenAPI Endpoint Filtering Protocol parses the specification locally and extracts strictly the target path, its HTTP method parameters, and its transitively resolved $ref schema components.

Monolithic OpenAPI Spec vs. Targeted Endpoint Slice

┌─────────────────────────────────────────────────────────────┐
│                 OpenAPI Specification Slicing               │
│                                                             │
│  Monolithic OpenAPI Ingestion (85,000 Tokens):              │
│  • 350 REST Endpoints (Billing, Users, Webhooks, Org, IAM)  │
│  • 600 Component Schemas and Error Enums                    │
│  ↳ 85,000 tokens billed, blows context limit                │
│                                                             │
│  Targeted Endpoint Slice (280 Tokens - 99.6% Reduction!):   │
│  • Path: `POST /v1/refunds`                                 │
│  • RequestBody: `RefundCreateRequest` ($ref resolved)       │
│  • Responses: `201 (RefundObject)`, `400 (APIError)`        │
│  ↳ 280 clean tokens, 100% exact contract fidelity           │
└─────────────────────────────────────────────────────────────┘

The 3-Step OpenAPI Slicing Algorithm

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. LOCATE TARGET ROUTE: Extract `paths["/v1/target"]["post"]`              │
│ 2. RECURSIVELY RESOLVE `$ref`: Extract only referenced `components/schemas`│
│ 3. STRIP UNRELATED METADATA: Drop servers, security schemes, other paths  │
└───────────────────────────────────────────────────────────────────────────┘

Production Python OpenAPI Route Slicer

Use this script to slice any monolithic Swagger/OpenAPI spec before passing it to an LLM:

import json
from pathlib import Path
from typing import Dict, Any, Set

def resolve_refs(schema_node: Any, full_spec: Dict[str, Any], collected_schemas: Dict[str, Any]) -> None:
    """Recursively resolves and collects all $ref components used in a schema."""
    if isinstance(schema_node, dict):
        for k, v in schema_node.items():
            if k == "$ref" and isinstance(v, str):
                ref_name = v.split("/")[-1]
                if ref_name not in collected_schemas and "components" in full_spec:
                    schema_def = full_spec.get("components", {}).get("schemas", {}).get(ref_name)
                    if schema_def:
                        collected_schemas[ref_name] = schema_def
                        resolve_refs(schema_def, full_spec, collected_schemas)
            else:
                resolve_refs(v, full_spec, collected_schemas)
    elif isinstance(schema_node, list):
        for item in schema_node:
            resolve_refs(item, full_spec, collected_schemas)

def extract_openapi_endpoint(spec_path: Path, target_path: str, target_method: str = "post") -> Dict[str, Any]:
    """Extracts a self-contained sub-schema for a single endpoint."""
    full_spec = json.loads(spec_path.read_text(encoding="utf-8"))
    
    path_item = full_spec.get("paths", {}).get(target_path, {})
    operation = path_item.get(target_method.lower())
    if not operation:
        raise ValueError(f"Endpoint {target_method.upper()} {target_path} not found in spec.")
        
    collected_schemas: Dict[str, Any] = {}
    resolve_refs(operation, full_spec, collected_schemas)
    
    return {
        "openapi": full_spec.get("openapi", "3.0.0"),
        "endpoint": f"{target_method.upper()} {target_path}",
        "operation": operation,
        "referenced_schemas": collected_schemas
    }

Benchmark Comparison

Integrating a single payment refund endpoint from a large enterprise API spec:

Agent Operational Directive

MANDATORY: Autonomous agents must NEVER ingest complete OpenAPI/Swagger specification files. Always parse and slice the spec down to the specific path and its referenced schemas before feeding it to LLM context.