Ir al contenido principal

Glosario de IA Operations

¿Qué es una especificación de API?

Especificación de API (API Specification)

← Todos los términos del glosario
En pocas palabras

Una descripción formal y legible por máquina de los endpoints, esquemas de datos, autenticación y errores de una API, como un documento OpenAPI.

Explicación

Una especificación de API es una descripción formal de cómo funciona una API: qué endpoints u operaciones ofrece, qué debe llevar cada petición, qué devuelve cada respuesta, cómo funciona la autenticación y qué errores pueden darse. Escrita en un formato estándar que lee una máquina, como OpenAPI, a menudo con JSON Schema para los datos, permite que clientes y servidores se entiendan sin ambigüedad. El mismo documento sirve para la documentación, los servidores mock, el código de cliente generado y las pruebas de contrato. En los sistemas de IA también importa para el tool calling, porque el modelo debe producir llamadas que encajen con un esquema estricto.

Qué contiene una especificación de API

  • Operaciones: las rutas o métodos disponibles, como GET /orders/{id}.
  • Parámetros y cuerpos de petición, con tipos, campos obligatorios y valores permitidos.
  • Respuestas para cada código de estado, con sus esquemas de datos.
  • Esquemas de autenticación y autorización.
  • Formatos y códigos de error.
  • Descripciones y ejemplos que explican la intención a las personas, y a los modelos.

Para qué se usa

  • Documentación que se mantiene al día con la API.
  • Servidores mock para que los equipos de front y back trabajen en paralelo.
  • Código de cliente y de servidor generado en varios lenguajes.
  • Pruebas de contrato que fallan cuando una implementación se aparta de lo acordado.
  • Validación de peticiones y respuestas en tiempo de ejecución, por ejemplo en un API gateway.

En un enfoque API-first o guiado por especificaciones, la especificación se acuerda antes de escribir el código.

Especificaciones de API y agentes de IA

Cuando un modelo de lenguaje llama a una herramienta, tiene que producir argumentos que encajen con un esquema. Las definiciones de herramientas de la mayoría de las plataformas de IA usan JSON Schema, y a menudo un documento OpenAPI existente se puede convertir en herramientas para un agente. Nombres, descripciones y ejemplos claros en la especificación ayudan al modelo a elegir la operación correcta y a rellenar bien los argumentos. Validar las llamadas del modelo contra el esquema antes de ejecutarlas es una protección básica.

Preguntas frecuentes

¿Qué es una especificación de API en pocas palabras?

Es una descripción precisa y estructurada de lo que ofrece una API y de cómo usarla: qué enviar, qué recibes y qué errores pueden darse. La pueden leer tanto personas como programas.

¿Qué diferencia hay entre OpenAPI y Swagger?

Swagger era el nombre original de la especificación y de un conjunto de herramientas. La especificación se donó a la OpenAPI Initiative y pasó a llamarse OpenAPI Specification; Swagger sigue siendo el nombre de una familia de herramientas que trabajan con ella.

¿Qué diferencia hay entre la documentación y la especificación de una API?

La especificación es el contrato formal que lee una máquina. La documentación es la explicación pensada para personas, que puede generarse a partir de la especificación y completarse con guías y ejemplos.

¿Para qué sirve JSON Schema?

JSON Schema describe la estructura de unos datos JSON: qué campos hay, de qué tipo son y cuáles son obligatorios. OpenAPI lo usa para definir los cuerpos de petición y respuesta, y las plataformas de IA para definir los argumentos de las herramientas.

¿Por qué importan las especificaciones de API a los agentes de IA?

Los agentes llaman a las APIs como herramientas y necesitan una descripción precisa de cada operación para hacerlo bien. Una buena especificación reduce las llamadas erróneas, y validar las llamadas contra ella evita que lleguen peticiones mal formadas a tus sistemas.

Dónde aparece en Thinkia

Productos

Para seguir leyendo

Fuentes

Actualizado: 2026-10-21

¿Quieres ver cómo se aplica en tu organización?

Habla con un experto en IA