API REST con OpenAPI: diseño, versionado y formato de errores

Una buena API REST sigue cinco reglas: recursos en lugar de acciones en la URL, una descripción OpenAPI mantenida como contrato, códigos de estado y formatos de error uniformes, versionado con periodo de migración en lugar de sorpresas y comprobaciones automáticas frente a la especificación. Quien lo define pronto ahorra esfuerzo de integración, consultas de soporte y problemas con las actualizaciones.

Ya sea una tienda online, un CRM, una app móvil o un portal para socios: el software moderno está interconectado y la calidad de las interfaces decide lo fluida que es esa conexión. Este artículo recorre el modelo de recursos, OpenAPI, convenciones, gestión de errores, versionado, seguridad y pruebas, con tablas que sirven de checklist para su propia API.

Recursos en lugar de acciones en las URL

REST piensa en recursos, no en llamadas a funciones. En lugar de endpoints como /getOrder o /createOrder existe un recurso /orders al que se accede mediante métodos HTTP. Los métodos tienen propiedades definidas en las que los clientes pueden apoyarse:

Método y ejemplo	Finalidad	Idempotente	Respuesta típica
GET /orders y GET /orders/{id}	leer una lista o un pedido concreto	sí	200
POST /orders	crear un pedido nuevo	no, salvo con clave de idempotencia	201 con cabecera Location
PUT /orders/{id}	sustituir un pedido por completo	sí	200 o 204
PATCH /orders/{id}	modificar campos concretos	no garantizado	200 o 204
DELETE /orders/{id}	eliminar un pedido, si lo permiten las reglas de negocio	sí	204

Esta coherencia hace predecible una API: quien ha entendido un endpoint entiende los demás. Los recursos anidados como /customers/{id}/orders tienen sentido cuando la relación es inequívoca desde el punto de vista funcional; un anidamiento demasiado profundo dificulta la lectura de la API. Complete con reglas uniformes de filtrado y ordenación. En la paginación, un procedimiento con cursor es más estable que los números de página con conjuntos de datos grandes o cambiantes, porque no se omiten ni se repiten entradas cuando se añaden datos entre dos consultas.

OpenAPI: el contrato entre sistemas

La especificación OpenAPI describe una API REST de forma legible por máquinas: endpoints, parámetros, esquemas de datos, ejemplos y posibles respuestas. Es, por tanto, documentación y contrato a la vez. Actualmente están extendidas las versiones 3.0 y 3.1; la 3.1 utiliza JSON Schema para los modelos de datos. Antes de elegir, compruebe qué versión admiten por completo sus herramientas.

Qué aporta una especifica­ción mantenida

• Los desarrolladores ven al instante qué campos se esperan y se devuelven, y encuentran ejemplos realistas de peticiones, respuestas y casos de error.
• A partir de la especificación se pueden generar clientes para distintos lenguajes de programación y documentación interactiva.
• Los servidores simulados (mock), por ejemplo con Prism, permiten a los equipos de frontend trabajar en paralelo antes de que el backend esté terminado.
• Linters como Spectral comprueban automáticamente la guía de estilo y herramientas como oasdiff señalan cambios incompatibles en los pull requests.
• También las aplicaciones de IA que deban usar su API como herramienta se benefician de una descripción precisa, con nombres de campo claros y ejemplos.

¿Design first o code first?

Con el enfoque design first, la especificación se acuerda antes de la implementación. Compensa especialmente en las API para socios, porque todos los implicados hablan pronto sobre la misma base. Con el enfoque code first, la especificación se genera a partir del código, lo que en las API internas suele ser más rápido. En ambos casos, la especificación debe estar en el repositorio y una comprobación en el pipeline garantiza que no se aparte del comportamiento real.

Convenciones que facilitan el día a día

Muchos problemas en los proyectos de integración no nacen de una lógica compleja, sino de detalles incoherentes. Fije las convenciones pronto y recójalas en una breve guía de estilo de API:

• Nomenclatura: una grafía uniforme para los campos, por ejemplo camelCase o snake_case, y recursos en plural.
• Fechas y horas: siempre según ISO 8601 con zona horaria.
• Importes: no como número de coma flotante, sino como entero de la unidad más pequeña o como cadena de texto, siempre con código de moneda.
• Idempotencia: las peticiones repetidas no deben crear pedidos duplicados, por ejemplo mediante una clave de idempotencia en las peticiones POST.
• Paginación: un procedimiento uniforme, con indicación de si hay más datos.
• Campos estructurados: campos separados en lugar de cadenas compuestas que el receptor debe descomponer.

Cultura de errores: códigos de estado y formato de errores

Una API demuestra su calidad sobre todo cuando algo sale mal. Unos códigos de estado claros ahorran tiempo de soporte, porque los desarrolladores ven enseguida dónde está el problema:

Código	Significado	Uso típico
400	petición no válida	JSON mal formado, parámetros ausentes
401	no autenticado	token ausente o caducado
403	sin permiso	autenticación válida, pero sin derechos
404	no encontrado	el recurso no existe o no es visible
409	conflicto	edición simultánea, alta duplicada
422	no procesable	formalmente correcto, pero falla la validación funcional
429	demasiadas peticiones	límite de tasa alcanzado, con cabecera Retry-After
503	servicio no disponible	mantenimiento o sobrecarga, con cabecera Retry-After

Igual de importante es un formato de errores uniforme. Se ha consolidado el estándar “Problem Details for HTTP APIs” (RFC 9457), con el tipo de medio application/problem+json y los campos type, title, status, detail e instance. En los errores de validación se añade una lista que indica qué campo se rechazó y por qué. El tipo de error debe ser legible por máquinas para que los clientes puedan reaccionar de forma específica; los stacktraces y los detalles internos no deben aparecer en la respuesta. Evite sobre todo responder a los errores con estado 200 y un mensaje en el cuerpo, porque dificulta la gestión automática de errores en el cliente.

Versionado sin roturas

Las API evolucionan. La mayoría de los cambios pueden hacerse de forma aditiva sin necesitar una versión nueva, siempre que los clientes ignoren los campos desconocidos. Conviene dejar esta regla escrita de forma expresa en la documentación. El resumen muestra lo que se considera un cambio incompatible:

Cambio	¿Cambio incompatible?
campo opcional nuevo en la respuesta	no
endpoint nuevo o parámetro opcional nuevo	no
eliminar o renombrar un campo	sí
cambiar el tipo de dato o el formato de un campo	sí
campo obligatorio nuevo en la petición	sí
valor nuevo en una enumeración (enum)	posible si los clientes no toleran valores desconocidos
cambiar el significado o el código de estado de un comportamiento	sí
cambiar el método de autenticación	sí

Hay varias formas de gestionar la versión mayor. La versión en la ruta, por ejemplo /v1/orders, se ve con facilidad, es sencilla de probar y de cachear y se ha impuesto en las API para socios. La versión en una cabecera o en el tipo de medio mantiene estables las URL, pero es más laboriosa de documentar y de probar. Aumente la versión mayor solo cuando haya cambios incompatibles.

Lo decisivo es cómo se gestionan los cambios. Los cambios incompatibles solo deben hacerse con un periodo de migración, documentado en el registro de cambios y anunciado mediante avisos de obsolescencia (deprecation). La cabecera Sunset (RFC 8594) informa a los clientes de forma legible por máquinas de cuándo se retirará una versión. En las API para socios planificamos normalmente de 90 a 180 días de funcionamiento en paralelo. En las apps móviles conviene contar con más tiempo, porque las versiones antiguas de la app siguen en circulación; ayudan una versión mínima y un aviso discreto para actualizar. Registre qué clientes usan qué versión para saber a quién contactar antes de la retirada.

Calidad y protección: pruebas de contrato y seguridad

Las pruebas de contrato comprueban si una API cumple las expectativas de sus consumidores. Con Pact, los consumidores definen qué peticiones y respuestas esperan y el backend se prueba contra ellas en cada despliegue. Además, las respuestas pueden validarse automáticamente frente a la descripción OpenAPI y comprobarse con muchas entradas generadas a partir de la especificación con herramientas como Schemathesis. Así se detectan cambios involuntarios antes de que afecten a los socios.

Toda API productiva necesita además medidas de protección. Para el acceso de socios y servidores se ha consolidado OAuth 2.0, a menudo con credenciales de cliente en los accesos de servidor a servidor; las claves de API solo son defendibles con permisos claramente limitados. El mayor riesgo suele ser la falta de autorización a nivel de objeto: en cada petición no basta con comprobar que quien llama ha iniciado sesión, sino que puede acceder exactamente a ese recurso. Esta vulnerabilidad encabeza el OWASP API Security Top 10 (edición de 2023). A ello se suman la limitación de tasa, la validación de entradas según el esquema y registros que permitan seguir los errores sin almacenar datos sensibles. Una visión general de los riesgos habituales la ofrece nuestra checklist de seguridad web OWASP.

Ejemplo práctico y lista de comprobación

Interfaces en el día a día de la empresa

En muchos proyectos, las API conectan sistemas existentes, por ejemplo un portal CRM inmobiliario con el software de agentes onOffice, una tienda online con el ERP o una app móvil con su backend. Supongamos que un comerciante ofrece a sus socios una API de pedidos. Dos años después, el campo price debe dividirse en unitPrice y currency. El camino limpio: los campos nuevos aparecen además del antiguo, price se marca como obsoleto y se anuncia en el registro de cambios, y se fija una fecha de retirada con margen suficiente. Los registros muestran qué socios siguen leyendo price y se les contacta de forma individual. Solo entonces se elimina el campo antiguo, en una versión mayor nueva si era obligatorio. Cómo se planifican estas conexiones se explica en el artículo Conectar ERP, CRM y tienda online.

Estos contratos también son imprescindibles entre los servicios de un sistema distribuido. Si dividir en servicios tiene sentido para su producto se aclara en el artículo Microservicios o monolito.

Lista de comprobación para su API

• Los recursos y endpoints siguen un esquema uniforme y los métodos HTTP se usan correctamente.
• Hay una especificación OpenAPI completa con ejemplos en el repositorio, que se comprueba en el pipeline.
• Los códigos de estado y el formato de errores (RFC 9457) están definidos de forma uniforme.
• La paginación, el filtrado, la ordenación y los formatos de fecha e importe están regulados.
• La estrategia de versionado, las reglas sobre cambios incompatibles y el periodo de migración están documentados.
• Las pruebas de contrato y una comprobación de cambios incompatibles se ejecutan automáticamente en el pipeline.
• La autenticación, la autorización a nivel de objeto y la limitación de tasa están implementadas.
• Los accesos se registran sin almacenar datos sensibles y el uso por versión puede analizarse.

Cómo le ayuda Nano Concepts

Si planea una API nueva o quiere mejorar una existente, le apoyamos con nuestro desarrollo de API y backend, desde el diseño de la descripción OpenAPI y la implementación hasta la conexión de sistemas existentes. En la primera consulta gratuita aclaramos qué interfaces necesita, quién las usará y cómo pueden desplegarse los cambios en el futuro sin roturas.