Definición de API: qué es
La definición de API es el contrato documentado que describe cómo un cliente debe llamar a una API y cómo responderá la API. Normalmente incluye rutas de endpoints, formatos de solicitud/respuesta (por ejemplo, campos JSON), tipos de datos, parámetros obligatorios vs. opcionales, autenticación y permisos, límites de tasa, formatos de error y cualquier expectativa declarada de sincronización u orden.
En un contexto de trading automatizado, la definición de API importa porque cada paso posterior—ingesta de datos, lógica de señales, decisiones de ejecución y generación de informes—depende de lo que la API garantiza frente a lo que meramente “intenta” proporcionar. El objetivo clave de la evaluación es comprender qué partes son mecánica estable y qué partes pueden variar con las condiciones del mercado, la carga del sistema y las políticas del proveedor.
Cómo comprobar una definición de API (lista de verificación objetiva)
- Integridad del contrato (puntos de atención)
- Los endpoints y métodos están explícitamente enumerados.
- Los esquemas de solicitud y respuesta están definidos, incluidos los significados de los campos y los tipos de datos.
- Existen ejemplos para respuestas normales y para cada tipo de error documentado.
- Se indican los requisitos de autenticación y autorización (por ejemplo, cómo se proporcionan las credenciales y qué acceso se permite).
- Detalles de comportamiento (la parte de “cómo funciona”)
- Confirma si la API define orden o consistencia entre llamadas (por ejemplo, si “lo más reciente” está vinculado a una marca de tiempo).
- Comprueba cómo se representan las marcas de tiempo (formato, zona horaria y si reflejan el tiempo del evento o el tiempo de procesamiento).
- Verifica cómo funcionan la paginación, el filtrado y los límites, incluidos los tamaños máximos de página y los valores predeterminados.
- Condiciones variables vs. mecánica estable
- Separa los elementos estables (esquema, reglas de parámetros, códigos de error documentados) de los elementos variables (latencia, vacíos en los datos, movimiento del mercado, limitación por carga).
- Trata cualquier declaración sobre “tiempo real” o “streaming” como una afirmación de comportamiento que debes verificar mediante pruebas o respuestas de muestra, no como una promesa fija.
- Evidencia y prueba documental Busca artefactos de implementación que te permitan validar el contrato:
- Documentación que incluya cargas útiles de muestra y respuestas de error.
- Política de versionado que describa cómo se introducen los cambios y durante cuánto tiempo se admiten las versiones antiguas.
- Recursos de prueba como entornos sandbox, endpoints simulados o llamadas de ejemplo registradas.
- Declaraciones claras de limitaciones (banderas rojas) Identifica vacíos donde la documentación es silenciosa o ambigua:
- Definiciones faltantes para campos críticos.
- Semántica de errores poco clara (por ejemplo, si un error se puede reintentar).
- Sin descripción de la contrapresión, el comportamiento de limitación de tasa o qué sucede durante interrupciones parciales.
Evidencia o ejemplo: qué significa “verificación”
Un ejemplo práctico de evaluación basada en evidencia es ejecutar llamadas con script que cubran:
- Una solicitud de “camino feliz” y confirmar que los campos de respuesta coinciden con el esquema documentado.
- Al menos una condición límite, como un parámetro no válido que debería desencadenar un error documentado.
- Una comprobación de latencia/sincronización midiendo el tiempo de ida y vuelta y comparándolo con cualquier expectativa de sincronización declarada.
Ejemplo de suposición (decláralo explícitamente): si mides el tiempo de respuesta desde el reloj de tu propio sistema, asumes que tu reloj está razonablemente sincronizado. Sin esa suposición, las comparaciones de sincronización pueden ser engañosas.
Limitaciones y modos de fallo a tener en cuenta
Como mínimo, evalúa al menos un modo de fallo material:
- Vacíos de datos: la API puede devolver historial incompleto, eventos faltantes o actualizaciones retrasadas.
- Problemas de latencia y orden: incluso si existen marcas de tiempo, el orden de las llamadas puede no coincidir con el orden de los eventos.
- Limitación de tasa o estrangulamiento: las solicitudes excesivas pueden provocar retrasos o errores estructurados.
- Desviación de esquema: las versiones de la API pueden cambiar campos, tipos o parámetros obligatorios.
- Fallos de autenticación/permisos: los tokens pueden caducar o los alcances de acceso pueden diferir según el entorno.
Las relaciones históricas no establecen resultados futuros. Incluso si las respuestas de muestra parecen consistentes, el comportamiento futuro puede cambiar cuando el proveedor actualiza los servicios o cuando cambian la carga del sistema y la volatilidad del mercado. Los resultados también varían según los costos, el método de ejecución y la jurisdicción, por lo que trata la definición de API como una descripción de contrato, no como una garantía de rendimiento.
Criterios de verificación y siguientes preguntas
Usa un “criterio de finalización” claro antes de integrar:
- Puedes asignar cada parámetro obligatorio y cada campo devuelto a un significado documentado.
- Puedes reproducir respuestas de éxito y error documentadas en un entorno de prueba.
- Has documentado las suposiciones sobre sincronización, reintentos e integridad de los datos.
- Tienes un plan para manejar límites de tasa, campos desconocidos y cambios de versión.
Siguientes preguntas para hacer durante la evaluación:
- ¿Cuál es exactamente el modelo de consistencia documentado de la API para marcas de tiempo y orden? - ¿Qué errores se pueden reintentar y qué orientación de backoff se proporciona?