LAPIS: Lightweight API Specification for Intelligent Systems

1. Problem Statement

The emergence of Large Language Models (LLMs) as primary consumers of API specifications (for code generation, autonomous agents, and reasoning) has exposed a critical inefficiency in the current industry standard, OpenAPI Specification (OAS).

• Design Mismatch: OpenAPI was designed (2010–2015) for human documentation, SDK generation, and testing tools. It prioritizes exhaustive JSON Schema typing, redundant metadata, and detailed examples.
• Token Overhead: When fed to LLMs, OpenAPI introduces massive "token waste" due to:
  • Structural Overhead: Deeply nested JSON Schema structures (e.g., type, properties, required) that humans would express in a single line.
  • Error Duplication: Identical error definitions (e.g., 401 Unauthorized) are repeated for every single operation. In the GitHub API, this results in ~1,594 error definitions for 1,080 endpoints.
  • Irrelevant Metadata: Fields like contact info, licenses, and tags consume context window space without aiding LLM reasoning.
  • Missing Operational Context: Crucial information for agents (rate limits, webhook triggers, operation flows) is often absent or buried in unstructured text.
• Consequence: This inefficiency increases inference costs, limits the complexity of APIs that can fit into context windows, and degrades model performance.

2. Methodology

The authors propose LAPIS (Lightweight API Specification for Intelligent Systems), a domain-specific format optimized for LLM consumption.

• Design Principles:
  • Token Minimality: Targeting 70–80% fewer tokens than OpenAPI YAML.
  • LLM-Native Syntax: Uses natural-language-adjacent syntax (function signatures, indentation-based grouping) rather than nested JSON/YAML.
  • Lossless Conversion: Deterministic rules to convert OpenAPI 3.x to LAPIS without manual intervention.
  • Semantic Completeness: Retains all information necessary for reasoning while discarding data useful only for code generation (e.g., strict XML hints).
• Format Structure: A LAPIS document consists of up to seven sections:
  1. [meta]: API name, base URL, auth (required).
  2. [types]: Reusable type definitions (objects, enums).
  3. [ops]: Operations with signature-based syntax (required).
  4. [webhooks]: Push events with trigger conditions.
  5. [errors]: Centralized error definitions (defined once globally).
  6. [limits]: Structured rate limits and quotas.
  7. [flows]: Multi-step operation sequences.
• Key Innovations:
  • Centralized Errors: Errors are defined once in a global section and referenced, eliminating duplication.
  • Signature Syntax: Operations use directional markers (> for inputs, < for outputs) and inline types, avoiding deep nesting.
  • Structured Operational Context: Explicit syntax for webhook triggers (!), rate limits, and operation flows (->, *, |).

3. Key Contributions

1. Formal Specification: Defined LAPIS v0.1.0 with syntax, EBNF grammar, and type system.
2. Automated Conversion: A deterministic conversion pipeline from OpenAPI 3.x to LAPIS (implemented as a Python package lapis-spec and a web tool).
3. Empirical Evaluation: A rigorous benchmark against five real-world production APIs (GitHub, Twilio, DigitalOcean, Petstore, HTTPBin).
4. Structural Analysis: Quantified the "structural waste" in OpenAPI, demonstrating that error duplication and metadata are the primary sources of token bloat.

4. Results

The evaluation measured token counts using the cl100k_base (GPT-4) and o200k_base (GPT-4o) tokenizers.

• Token Reduction:
  • Average Reduction: 85.5% compared to OpenAPI YAML.
  • Range: 71.9% (HTTPBin) to 92.1% (Twilio).
  • Comparison: LAPIS outperforms even minified OpenAPI JSON, proving savings come from structural redesign, not just whitespace removal.
• Case Study (GitHub API):
  • OpenAPI YAML: ~1.81 million tokens.
  • LAPIS: ~313,000 tokens.
  • Reduction: 82.7%.
  • Error Handling: Reduced 1,594 error definitions to just 14 unique lines.
• Scalability: Token reduction increases with API complexity (number of types and endpoints), as larger APIs benefit more from type deduplication and error centralization.
• Cost Implications: For the GitHub API, using LAPIS reduces the cost of including the spec in an LLM context from ~$5.44 per call (YAML) to ~$0.94 (LAPIS) at current pricing, a savings of ~$4,500 per 1,000 calls.

5. Significance

• Paradigm Shift: LAPIS challenges the assumption that OpenAPI is the universal standard for all API consumers. It establishes that LLMs require a fundamentally different representation than human developers or code generators.
• Economic Impact: By drastically reducing token usage, LAPIS makes it economically feasible to include massive, complex API specifications in LLM context windows, enabling more sophisticated autonomous agents.
• Enhanced Reasoning: Unlike simple compression (e.g., TOON), LAPIS adds structured information (rate limits, flows, triggers) that OpenAPI lacks, providing more semantic value per token.
• Ecosystem Compatibility: LAPIS is designed as a conversion target, not a replacement. Organizations maintain OpenAPI as their "source of truth" for documentation and tooling, converting to LAPIS only when the consumer is an LLM.
• Open Standard: Released under CC BY 4.0 with open-source tools (converter, VS Code extension), fostering immediate adoption and further research.

In conclusion, LAPIS addresses the "token tax" of API specifications by re-engineering the format for the specific cognitive and economic constraints of Large Language Models, offering a highly efficient, semantically rich alternative to OpenAPI for AI-driven development.