¿Integraciones torpes y APIs confusas frenan las ventas y consumen al equipo? Una pyme con web obsoleta suele perder tiempo y clientes por contratos técnicos imprecisos, documentación escasa y convenciones inconsistentes; necesita instrucciones claras, plantillas reutilizables y reglas de nombrado que el proveedor o el equipo puedan aplicar sin riesgos.
Para diseñar APIs REST efectivas empieza por modelar recursos claros y URIs consistentes, usar métodos HTTP correctamente, estandarizar respuestas JSON y códigos de error, aplicar versionado y seguridad (OAuth2/JWT) y documentar con OpenAPI.
Se incluyen ejemplos y una plantilla mínima de OpenAPI dentro del artículo (openapi: 3.0.3 con paths y componentes); para obtener plantillas más completas conviene publicar un paquete con openapi.yaml, components/, examples/ y una colección Postman (postman-collection.json) en el repositorio del proyecto, de modo que clientes y proveedores puedan importar la especificación directamente.
Resumen del proceso
- Mapear recursos y casos de uso: listar productos, clientes, pedidos y eventos.
- Definir contrato OpenAPI v3 con paths y esquemas: generar mocks y ejemplos.
- Añadir seguridad y gateway: OAuth2/JWT, TLS y rate limiting.
- Implementar pruebas contractuales y pipelines CI/CD: validar OpenAPI en cada merge.
- Desplegar con control de versiones y observabilidad: métricas, logs y trazas.
Paso 1: mapear recursos y contratos
Define los recursos principales y el resultado será un diagrama claro de endpoints.
Documentar recursos evita malentendidos con el equipo y proveedores.
El mapa mínimo incluye: products, customers, orders, payments y webhooks.
Identifica acciones complejas y convierte acciones en subrecursos.
Por ejemplo, cancelar un pedido será POST a /orders/{id}/cancel en vez de /cancelOrder.
Recursos y URIs
Usar nombres en plural mejora la consistencia y el descubrimiento.
Ejemplos concretos: /products, /products/{productId}, /customers/{customerId}/addresses.
Evitar verbos en URIs reduce errores frecuentes en integraciones.
El error típico aquí es usar rutas como /getProducts que obligan a convenciones distintas por cliente.
Decidir UUIDs o slugs desde el inicio evita migraciones complejas después.
Para tiendas, UUIDs evitan colisiones y facilitan sincronización con marketplaces.
Si se usa slug legible, reservar un campo inmutable para referencias internas.
Esto tarda entre 1 y 2 horas en definirse en un sprint pequeño, pero ahorra días en integraciones.
Convenciones concretas para URIs y nombres. Usa siempre nombres de recursos en plural y en minúsculas con kebab-case (/product-categories, /products), reserva acciones tipo verbo como subrecursos o headers (POST /orders/{orderId}/cancel es aceptable como subrecurso de acción). Evita rutas con verbos directos (/getProducts) y limita anidamientos a una o dos capas (/customers/{customerId}/addresses/{addressId}), no encadenes seis niveles. Para identificadores usa nombres claros (productId, orderId) y prefiere UUIDs para APIs públicas; declara el formato en el esquema (format: uuid). Para queries, normaliza parámetros: page + limit o cursor + limit para paginación, sort=field,-field para orden, filter[status]=paid para filtros compuestos.
Usa PATCH para actualizaciones parciales, PUT para reemplazos completos y devuelve códigos claros (201, 204, 400, 404, 409). Estas reglas reducen ambigüedades entre equipos y mejoran el descubrimiento automático por clientes y gateways.
Paso 2: escribir la OpenAPI y ejemplos
Genera una OpenAPI v3 completa y el resultado será un contrato que sirve para dev y QA.
Incluye paths, components.schemas, securitySchemes y ejemplos de request/response.
OpenAPI v3 es un formato ampliamente aceptado por herramientas como Swagger y Postman.
Añade ejemplos de responses 200 y de errores con trace_id para correlación.
Una OpenAPI completa reduce cambios de alcance y acorta tiempos de entrega con proveedores.
Plantilla mínima OpenAPI
A continuación se incluye una OpenAPI mínima lista para copiar y ampliar.
Yaml
openapi: 3.0.3
info:
title: Tienda API
version: "1.0.0"
paths:
/products:
get:
summary: Lista productos
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ProductList'
components:
schemas:
ProductList:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Product'
Product:
type: object
properties:
id:
type: string
name:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
Generar mocks y SDKs
Generar mocks reduce tiempo de front y pruebas; OpenAPI Generator crea SDKs en minutos.
Esto funciona bien en teoría, pero en la práctica conviene revisar los modelos generados.
Postman publica análisis del sector que sirven para priorizar endpoints a mockear (State of the API, 2021).
Generar un mock tarda entre 10 y 30 minutos por endpoint si el esquema está listo.
Ejemplo práctico paso a paso:
- Modelar, definir contrato y probar. Partiendo de un recurso Product, primero define el esquema mínimo en OpenAPI y añade un path con ejemplos.
- Por ejemplo, en OpenAPI declara
/products (GET) y /products (POST) con el body ProductCreate. Genera un mock a partir del OpenAPI y valida con un curl: curl -X POST https://api.example.com/v1/products -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"name":"Camiseta","sku":"CAM-001","price":19.9}'.
- En el backend, un handler mínimo en Express podría mapear al mismo path y validar contra el esquema, por ejemplo:
app.post('/v1/products', validateProductCreate, async (req, res) => { const product = await ProductService.create(req.body); res.status(201).json(product); }).
- Este flujo muestra cómo el contrato OpenAPI, el mock y el handler real encajan: la especificación genera los ejemplos para el frontend, el mock permite pruebas sin backend, y el handler implementa exactamente los campos y códigos HTTP previstos (201 para creación, 400 para validación).
Paso 3: definir esquema de errores y códigos HTTP
Establece un esquema de errores y obtendrás soporte más rápido y logs útiles.
Usar un esquema consistente evita que el soporte no sepa qué buscar.
Plantilla recomendada:
{
"http_status": 404,
"code": "PRODUCT_NOT_FOUND",
"message": "Producto no encontrado",
"details": null,
"trace_id": "<uuid>"
}
Asignar códigos internos claros mejora la respuesta al cliente y la monitorización.
No devolver mensajes de stack ni datos internos; enviar solo trace_id para diagnóstico.
Códigos HTTP recomendados
Usar 400 para validación, 401 para no autorizado, 403 para prohibido y 409 para conflictos.
Para picos usar 429 y para errores inesperados 5xx.
Un error frecuente es usar 200 con un body de error; esto rompe cachés y herramientas de cliente.
Corregirlo evita llamadas adicionales de soporte y reduce tiempo de resolución.
Trazabilidad y logging
Enviar trace_id en cada respuesta permite correlación con logs y trazas.
OpenTelemetry se integra bien para traza distribuida y métricas.
Registrar request_id en logs estructurados facilita auditoría y cumplimiento.
La correlación de trace_id suele detectar problemas que las pruebas no cubrieron.
Paso 4: seguridad práctica y API gateway
Protege la API con OAuth2/JWT y obtendrás control de acceso escalable.
OAuth2 (RFC 6749, 2012) es el estándar para autorización delegada; usar OpenID Connect para login.
Definir scopes claros como orders:read y orders:write mejora el control de permisos.
Configura TLS obligatorio en el servidor/API Gateway y establece HSTS mediante la cabecera Strict-Transport-Security desde el servidor para forzar HTTPS; el control se aplica en la capa que sirve las respuestas (gateway o servidor), no en el cliente frontend.
CORS debe restringirse a orígenes concretos en producción y nunca usar '*' en entornos reales.
Configuración de gateway
Usar un API Gateway proporciona autenticación, rate limiting y caching centralizados.
Opciones: AWS API Gateway, Apigee (Google) o Azure API Management según proveedor cloud.
Un ejemplo mínimo de policy incluye validación JWT, rate limit 100rpm y logging de trace_id.
Configurar esto en Terraform o CloudFormation facilita reproducir entornos.
Rotación y revocación de tokens
Planificar lifetimes y refresh tokens evita accesos indefinidos.
La revocación exige guardar un registro de tokens activos o usar introspection endpoint.
Un error típico es confiar solo en token lifetime y no ofrecer revocación, lo que complica incidentes de seguridad.
Esto tarda entre 1 y 3 días en implementarse en sistemas medianos.
Paso 5: patrones operativos para tiendas online
Aplica paginación, idempotencia y cacheo para mejorar fiabilidad y experiencia.
Paginación cursor-based funciona mejor en listados grandes y reduce inconsistencias con cambios concurrentes.
Incluir limit y next_cursor en responses facilita implementaciones cliente.
Requerir header Idempotency-Key en POSTs que crean pagos o pedidos evita duplicidades.
Guardar claves idempotencia durante al menos 24 horas para pedidos y 7 días para pagos según riesgo.
Cacheo y invalidación
Cachear GET con Cache-Control y ETag mejora latencia en endpoints read-heavy.
Invalidar caché al actualizar recursos críticos como stock.
Combinar CDN para assets y cache a nivel API Gateway suele reducir latencia para clientes en España y UE.
Los errores más frecuentes ocurren por no definir política de invalidación y servir datos obsoletos.
Webhooks y entrega fiable
Firmar payloads con HMAC y reintentar con backoff exponencial.
Registrar entregas y exponer un endpoint para que clientes verifiquen entrega y estado.
Limitar reintentos y alertar cuando un webhook falla más de N intentos.
Esto evita bucles infinitos y reduce costes en proveedores externos.
Comparativa técnica: REST, GraphQL y gRPC
Comprender diferencias permite elegir la tecnología adecuada para cada caso.
| Característica |
REST |
GraphQL |
gRPC |
| Caso de uso |
APIs públicas y CRUD para tiendas |
Consultas complejas entre entidades relacionadas |
Comunicación interna de microservicios de alto rendimiento |
| Curva de adopción |
Baja; compatible con navegadores y caches |
Media; requiere un gateway y control de esquemas |
Alta; requiere gRPC clients y HTTP/2 |
| Cacheo |
Sencillo con HTTP cache headers |
Complejo; hay que diseñar manualmente cachés |
Limitado; no es su fuerte |
| Rendimiento |
Bueno para la mayoría de tiendas |
Eficiente en consultas, pero requiere control |
Excelente para microservicios y baja latencia |
Infografía del flujo de diseño
1. Mapear
Recursos y casos de uso
2. Contrato
OpenAPI con ejemplos
3. Seguridad
OAuth2, TLS, gateway
4. Tests
Contratos y carga
5. Despliegue
CI/CD y observabilidad
Errores que arruinan el resultado
Evita cambios sin versionado para no romper integraciones en producción.
El error más frecuente en este punto es introducir campos nuevos en responses sin versionar la API.
Esto obliga a clientes a reescribir parsing y provoca fallos en producción.
No usar un esquema de errores consistente complica soporte y monitorización.
Si las respuestas de error no tienen http_status y trace_id, la depuración tarda mucho más.
Malas prácticas comunes
Usar verbos en URIs como /getUsers genera inconsistencias entre equipos.
No planificar idempotencia en endpoints que crean recursos duplica pedidos en momentos críticos.
Cómo evitarlas
Decidir versionado antes del lanzamiento y documentarlo en la OpenAPI.
Revisar cambios con pruebas contractuales en cada merge para evitar roturas.
Cuándo no funciona este método
No es prioritario diseñar una API propia cuando la web es estática o cuando se usa una API totalmente gestionada por terceros sin control sobre su diseño. Tampoco es la mejor opción frente a GraphQL si la aplicación requiere consultas ad-hoc complejas entre múltiples entidades.
Pruebas, observabilidad y CI/CD
Valida el contrato OpenAPI en CI para evitar despliegues que rompan clientes.
Pipeline básico: lint OpenAPI → tests contractuales → build → despliegue canario.
Métricas mínimas: latencia 95p, tasa de errores y throughput por endpoint.
Logs estructurados con trace_id permiten investigar incidentes y cumplir auditorías.
Tests obligatorios
Contract tests (Pact o validación OpenAPI) evitan regresiones en el contrato.
Pruebas de carga en endpoints de checkout y webhooks detectan cuellos de botella.
Plantilla GitHub actions
yaml
name: CI
on: [push]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Validate OpenAPI
run: |
npm install -g @redocly/openapi-cli
openapi lint api/openapi.yaml
Plantillas y snippets útiles
Incluye aquí ejemplos listos para copiar: esquema de error, OpenAPI mínimo y pipeline.
Copiar estas plantillas evita ambigüedades con proveedores y reduce tiempo de integración.
Plantilla de email para pedir
text
Asunto: Revisión técnica OpenAPI y pipeline
Hola [Nombre],
Adjunto la OpenAPI actual y solicito una revisión técnica centrada en seguridad, esquemas de error y pipeline CI/CD.
Por favor, confirma tiempo estimado y riesgos críticos.
Atentamente,
[Nombre Empresa]
(Usar este email para solicitar revisión al proveedor o equipo interno; adjuntar openapi.yaml en la petición.)
Checklist rápido para entrega
- OpenAPI v3 con ejemplos y securitySchemes.
- Esquema de error JSON con trace_id.
- Pipeline de CI que valida OpenAPI.
- Gateway configurado con rate limiting y JWT validation.
- Pruebas contractuales y pruebas de carga en staging.
Si se prefiere delegar la revisión técnica, se puede solicitar directamente usando la plantilla de email incluida y adjuntando el openapi.yaml.
Estructura de plantillas OpenAPIs: además del snippet del artículo, un paquete útil incluye al menos estos archivos: openapi.yaml (entrada principal con paths), components/schemas.yaml (esquemas compartidos), components/securitySchemes.yaml, examples/*.json (ejemplos de request/response), y postman-collection.json. Un README.md explica versiones y cómo generar mocks/SDKs con openapi-generator. Ejemplo de cabecera mínima de openapi.yaml: openapi: 3.0.3/ninfo:/n title: Tienda API/n version: '1.0.0'/npaths:/n /products:.
Tener estos ficheros en un repositorio o paquete ZIP permite a clientes y proveedores importar directamente la especificación en Postman/SwaggerHub y generar SDKs sin reescribir esquemas; incluye además un CHANGELOG.md para documentar cambios de versión y compatibilidad.
Preguntas frecuentes
¿Qué diferencia hay entre REST y GraphQL?
REST usa recursos y métodos HTTP; GraphQL expone un endpoint para consultas.
GraphQL reduce overfetching pero exige control de esquemas y caching manual.
Para catálogos grandes con relaciones complejas, GraphQL puede ser más eficiente.
URI-versionado es más simple y transparente para clientes variados.
Header-versionado ofrece URIs limpias pero añade complejidad en clientes simples.
Para pymes con clientes heterogéneos, URI-versionado suele ser la opción práctica.
¿Cómo manejar pagos y cumplimiento?
Delegar el pago a proveedores como Stripe reduce alcance PCI.
Registrar datos mínimos y enmascarar identificadores en logs para cumplir RGPD (2018).
Documentar flujos de datos y firmar acuerdos de tratamiento con terceros.
¿Qué pruebas son imprescindibles antes de desplegar?
Validación de contrato OpenAPI, pruebas de integración y pruebas de carga sobre endpoints críticos.
Incluir tests de seguridad básicos según OWASP API Security Top 10.
Las pruebas contractuales detectan cambios rompientes antes de afectar clientes.
¿Cuánto tiempo lleva tener una API lista?
Una API mínima con contrato y mocks puede estar lista en 2 a 4 semanas para un MVP.
La fase de pruebas y despliegue controlado añade entre 1 y 2 semanas más.
Migraciones completas y compliance pueden tardar entre 4 y 8 semanas según alcance.
¿Cuándo elegir microservicios backend en vez de un monolito?
Si el negocio necesita escalar módulos independientes y tienes equipo con experiencia, microservicios ayudan.
Para tiendas pequeñas, un monolito bien estructurado suele ser más rápido y barato.
La decisión depende de costes, skills y la complejidad del catálogo.
¿Qué métricas vigilar en producción?
Vigilar latencia 95/99 percentiles, tasa de errores 5xx y count de rate limits.
Monitorizar throughput por endpoint y tiempo medio de respuesta.
Alertar al alcanzar umbrales definidos para actuación rápida.
Cierre y siguientes pasos
La evidencia apunta a que definir contrato y versionado desde el inicio reduce tiempo de integración y evita costes de soporte.
OpenAPI v3 (2017), OAuth2 (RFC 6749, 2012) y la entrada en vigor del RGPD (2018) marcan prácticas y obligaciones actuales.
Los siguientes pasos prácticos: mapear recursos hoy, generar OpenAPI mañana y añadir validación en CI en la próxima semana.
Si hay dudas técnicas, usar la plantilla de email incluida para pedir una revisión al proveedor o al equipo.
