OpenAPI
OpenAPI describe interfaces HTTP en un formato legible por máquinas, con rutas, parámetros y respuestas. La descripción debe coincidir con el servicio.
Registrar un contrato comprensible de API HTTP
OpenAPI es un estándar para describir API HTTP. Una descripción OpenAPI registra, entre otros datos, las rutas, operaciones, parámetros y estructuras de respuesta disponibles. Puede representarse en JSON o YAML. El lenguaje de descripción no depende del lenguaje de programación con el que se construye el servicio.
Una empresa de software ficticia planifica GET /projects/{projectId} para su portal de proyectos. La descripción debe definir projectId como parámetro de ruta; la respuesta satisfactoria 200 debe incluir, entre otros, el campo de texto name. Las respuestas de error conocidas también forman parte del contrato. La ruta y los campos son ejemplos de diseño propios, no un documento OpenAPI completo ni un servicio existente.
El equipo de frontend puede entender qué información enviar y qué respuestas procesar. El archivo por sí solo no demuestra que la implementación en funcionamiento respete el contrato. Antes de la entrega habría que comparar la descripción con las respuestas reales, incluidos los errores. También debe acordarse el significado de name: una cadena con el tipo correcto no explica qué nombre contiene el campo.
Fuentes
Términos relacionados
- APIUna API define cómo un programa puede utilizar funciones o datos ofrecidos por otro programa.
- RESTREST establece reglas de arquitectura para interfaces distribuidas. Incluye recursos, solicitudes sin estado y enlaces.
- Server-Sent EventsServer-Sent Events transmite avisos de texto del servidor al cliente por HTTP, por ejemplo sobre el avance de un trabajo en segundo plano.
- ETagUn ETag identifica una versión concreta de la representación de un recurso HTTP y permite lecturas o cambios condicionales.
- Cross-Origin Resource SharingCORS controla el acceso del navegador a respuestas de otro origen. No sustituye el inicio de sesión ni la comprobación de permisos de la API.
- Intercambio electrónico de datosEDI transmite documentos de negocio estructurados entre sistemas. Deben concordar el formato, el perfil del socio, las correspondencias de datos y las respuestas.
Su proyecto con ASES
Descríbanos su proyecto. Le responderemos con una primera valoración.