Qué significa la Definición de API en la práctica
La Definición de API generalmente se refiere a la especificación formal de cómo funciona una API: los endpoints (u operaciones) disponibles, las entradas requeridas, las entradas opcionales, las salidas esperadas, los tipos de datos, las reglas de validación y los formatos de error. Puede estar escrita como un documento OpenAPI/Swagger, un esquema JSON, una especificación interna para desarrolladores o documentación legible para humanos.
Cuando verificas información sobre una Definición de API, no intentas confirmar que una idea sea “verdadera” en general—estás comprobando si el contrato documentado es consistente, comprobable y reproducible para una versión específica de la API.
Cómo funciona el proceso de verificación (jerarquía de fuentes)
Utiliza una jerarquía de fuentes que coincida con cómo se debe confirmar la “mecánica estable”.
-
Artefactos de contrato primarios (los más estables)
- El(los) documento(s) de definición de API real(es) publicados por el proveedor (por ejemplo, el archivo OpenAPI).
- Cualquier esquema legible por máquina incluido con la documentación.
- El identificador de versión documentado y el registro de cambios.
-
Documentación del proveedor (capa de interpretación)
- Guías que describen cómo formar solicitudes e interpretar respuestas.
- Secciones de manejo de errores y autenticación/autorización, si afectan la estructura de solicitud/respuesta.
-
Comportamiento observado a partir de una prueba controlada (verificación de la realidad)
- Un pequeño conjunto de solicitudes en un entorno que no sea de producción o en un sandbox cuando esté disponible.
- Validación de que los campos, tipos y restricciones de las respuestas coinciden con la definición.
En la práctica, la verificación es más sólida cuando puedes demostrar que la documentación, el esquema y las respuestas coinciden para la misma versión.
Evidencia y pasos de verificación reproducibles
Sigue un proceso paso a paso que puedas repetir.
Paso 1: Fija la versión y el alcance
Anota la versión de la API y el artefacto de definición exacto que estás utilizando (nombre de archivo, URL o identificador de commit). Supón que diferentes versiones pueden tener diferentes nombres de campos, parámetros requeridos y formatos de error.
Paso 2: Verifica la estructura contra la definición
Para cada endpoint que te interese, verifica que:
- La lista de parámetros requeridos sea explícita.
- Los parámetros opcionales sean distinguibles.
- Los campos de salida estén documentados con tipos de datos o esquemas.
- Las respuestas de error tengan una estructura documentada (por ejemplo, un código de error más un mensaje, o una lista de problemas de validación).
Paso 3: Crea casos de prueba mínimos con suposiciones explícitas
Elige un pequeño conjunto de solicitudes que cubran:
- Un caso de “ruta feliz” con solo los campos requeridos.
- Un caso de validación (tipo incorrecto intencionalmente o campo requerido faltante) para confirmar el comportamiento de error.
Supón que no hay datos de mercado en tiempo real. Si la API requiere parámetros que normalmente dependen de un estado externo (como símbolos o identificadores), utiliza valores que proporcione tu entorno de prueba, o trata los valores faltantes/inválidos como entradas de prueba en lugar de intentar predecir resultados.
Paso 4: Compara las respuestas con la definición
Para cada respuesta:
- Comprueba que el payload de la respuesta incluya los campos descritos.
- Comprueba que los tipos de datos coincidan con las expectativas (cadena vs número, objeto vs lista).
- Confirma que los errores tengan la forma documentada cuando las solicitudes sean inválidas.
Si la definición dice que un campo es opcional pero nunca aparece en las respuestas, eso es una discrepancia que debes registrar. Por el contrario, si aparecen campos adicionales de manera consistente, regístralos como “observados pero no documentados”, lo que puede indicar una brecha en la documentación.
Paso 5: Rastrea los modos de fallo, no solo los resultados
Al menos una limitación material debe ser parte de la verificación:
- Deriva de versión: la documentación puede ir por detrás del comportamiento después de las actualizaciones.
- Esquemas inconsistentes: los campos pueden estar documentados pero faltar o haber sido renombrados.
- Diferencias de validación: los formatos de error pueden cambiar entre endpoints.
- Diferencias de entorno: el comportamiento del sandbox y el de producción pueden no coincidir.
Trátalos como resultados de verificación, no como señales de corrección.
Limitaciones y riesgos a esperar
Incluso con comprobaciones cuidadosas, la verificación está limitada por la incertidumbre y el cambio.
- Ninguna prueba única garantiza la precisión a largo plazo. Una definición puede ser correcta hoy y quedar desactualizada después de las actualizaciones del proveedor.
- El comportamiento puede variar según el contexto. Los costos, las condiciones de ejecución, los permisos y las fallas de red pueden cambiar qué respuestas ves, incluso cuando el contrato es estable.
- El acuerdo histórico no asegura el acuerdo futuro. Si las respuestas coincidieron anteriormente, eso no garantiza que coincidan después de un cambio de versión.
Debido a estos límites, mantén la verificación vinculada a una versión específica y a un entorno de prueba específico.
Lista de verificación de verificación y siguiente pregunta a resolver
Usa esta lista de verificación para hacer tu verificación reproducible:
- Versión registrada tanto para la documentación como para las pruebas. - Endpoints y campos enumerados a partir de la definición. - Solicitudes mínimas de “ruta feliz” y “fallo de validación” creadas con suposiciones explícitas.