LAPIS: Lightweight API Specification for Intelligent Systems

Título: LAPIS: Especificação de API Leve para Sistemas Inteligentes

Subtítulo: Um Formato de Descrição de API Eficiente em Tokens para Janelas de Contexto de LLMs
Autor: Daniel García García (Pesquisador Independente, Espanha)
Data: Fevereiro de 2026

---

1. O Problema

O surgimento de agentes impulsionados por Grandes Modelos de Linguagem (LLMs), assistentes de codificação e consumidores autônomos de API criou uma nova classe de consumidor de especificações: o próprio modelo de linguagem. No entanto, o padrão de facto para descrição de APIs, o OpenAPI Specification (OAS), foi projetado entre 2010 e 2015 para consumidores diferentes: renderizadores de documentação (Swagger UI), geradores de SDKs e ferramentas de teste.

Essa incompatibilidade gera desperdício mensurável de tokens quando o OpenAPI é usado no contexto de um LLM:

• Sobrecarga Estrutural: O uso excessivo de JSON Schema aninhado (tipos, propriedades, requisitos) cria redundância.
• Duplicação de Erros: Respostas de erro (ex: 401, 404) são definidas repetidamente para cada operação, mesmo que idênticas. No caso da API do GitHub, o código 404 aparece 531 vezes.
• Metadados Irrelevantes: Campos como licenças, contatos, documentação externa e extensões x-* não agregam valor ao raciocínio do LLM.
• Falta de Contexto Operacional: Informações cruciais para o uso da API, como limites de taxa (rate limits), condições de gatilho para webhooks e sequenciamento de operações, muitas vezes estão ausentes ou escondidas em texto livre.

O resultado é um custo elevado de tokens e uma janela de contexto limitada, o que prejudica a capacidade do LLM de raciocinar sobre a API.

---

2. Metodologia e Proposta (LAPIS)

O artigo apresenta o LAPIS (Lightweight API Specification for Intelligent Systems), um formato específico de domínio otimizado para o consumo por LLMs. O LAPIS não substitui o OpenAPI como fonte da verdade para documentação humana, mas atua como um alvo de conversão para LLMs.

Princípios de Design:

1. Minimalismo de Tokens: Cada elemento sintático deve justificar seu custo. O objetivo é reduzir 70–80% o número de tokens em comparação com o OpenAPI YAML.
2. Sintaxe Nativa para LLM: Utiliza sintaxe próxima à linguagem natural (assinaturas de funções, indentação, tipos inline) em vez de estruturas JSON/YAML profundamente aninhadas.
3. Conversão Sem Perdas (de OpenAPI para LAPIS): A transformação é totalmente automatizável e determinística.
4. Legibilidade Humana: O formato deve ser autoexplicativo para desenvolvedores.
5. Completude Semântica: Preserva apenas as informações necessárias para o raciocínio do LLM, descartando detalhes de validação estrita de JSON Schema.

Estrutura do Documento LAPIS:
O formato é composto por até sete seções em ordem fixa:

• [meta]: Metadados da API (nome, URL base, autenticação).
• [types]: Definições de tipos reutilizáveis (objetos, enums).
• [ops]: Operações da API (endpoints) com sintaxe de assinatura (> inputs, < outputs).
• [webhooks]: Eventos de push com condições de gatilho semânticas.
• [errors]: Definições centralizadas de erros (evitando duplicação).
• [limits]: Limites de taxa e cotas estruturados.
• [flows]: Sequências de operações multi-etapa.

---

3. Contribuições Principais

1. Especificação Formal: Definição completa do formato LAPIS (v0.1.0), incluindo sintaxe, gramática EBNF e sistema de tipos.
2. Regras de Conversão Determinísticas: Um conjunto de regras para converter OpenAPI 3.x para LAPIS automaticamente (resolução de referências, achatamento de esquemas, centralização de erros).
3. Avaliação Empírica: Testes realizados em cinco APIs de produção reais (GitHub, Twilio, DigitalOcean, Petstore, HTTPBin).
4. Análise de Desperdício: Estudo detalhado da redundância estrutural em especificações OpenAPI do mundo real.
5. Ferramentas Abertas: Um conversor Python (lapis-spec), uma ferramenta baseada em navegador e uma extensão para VS Code, tudo sob licença CC BY 4.0.

---

4. Resultados da Avaliação

Os testes foram realizados comparando o tamanho em tokens (usando o tokenizador cl100k_base, padrão do GPT-4) entre o OpenAPI original e o formato LAPIS.

Redução de Tokens:

• Média Geral: Redução de 85,5% em comparação com OpenAPI YAML.
• Comparação com JSON: Redução de 88,6% em comparação com OpenAPI JSON.
• Casos Específicos:
  • GitHub (1.080 endpoints): De 1.811.843 tokens (YAML) para 313.101 tokens (LAPIS) → 82,7% de redução.
  • Twilio (197 endpoints): 92,1% de redução.
  • DigitalOcean (545 endpoints): 90,8% de redução.

Análise de Fontes de Economia:
A economia de tokens provém de quatro fontes principais:

1. Eliminação de Metadados (~25-30%): Remoção de campos irrelevantes para LLMs.
2. Sintaxe de Assinatura vs. Estrutura Aninhada (~25%): Substituição de hierarquias complexas por linhas únicas.
3. Compactação do Sistema de Tipos (~15%): Uso de enums de linha única e referências diretas.
4. Centralização de Erros (~10-20%): Definição única de códigos de erro em vez de repetição por operação.

Consistência: Os resultados foram consistentes entre diferentes tokenizadores (cl100k_base e o200k_base), com variações inferiores a 2%.

---

5. Significado e Impacto

• Economia Financeira Direta: A redução de tokens traduz-se diretamente em custos menores. Para uma aplicação que faz 1.000 chamadas diárias com o contexto da API do GitHub, o uso do LAPIS economizaria aproximadamente $4.497 por mil chamadas (baseado em preços de input de tokens de fevereiro de 2026).
• Maior Informação por Token: Diferente de formatos de compactação genéricos (como TOON), o LAPIS não apenas comprime, mas adiciona semântica estruturada (como gatilhos de webhook e fluxos de operação) que o OpenAPI não consegue representar nativamente. Isso permite que os LLMs planejem interações complexas e sequenciais.
• Complementaridade: O LAPIS é projetado para coexistir com o OpenAPI. As organizações mantêm o OpenAPI como fonte da verdade para documentação e ferramentas de código, convertendo para LAPIS apenas quando o consumidor é um LLM.
• Escalabilidade: A eficiência do formato aumenta com a complexidade da API (mais endpoints e tipos), pois há mais oportunidades para deduplicação e centralização.

Conclusão

O artigo demonstra que o desperdício de tokens em especificações de API para LLMs é um problema estrutural, não apenas de codificação. O LAPIS resolve isso redesenhando a estrutura da especificação para atender às necessidades específicas de raciocínio dos modelos de linguagem, oferecendo uma redução drástica de custos e permitindo o uso de APIs complexas em janelas de contexto limitadas, sem sacrificar a capacidade de inferência do modelo.