Diseño de una API pública: las decisiones detrás de nuestro lanzamiento
Por qué elegimos REST en vez de GraphQL, header en vez de query string y cuotas rolling en vez de calendario.
La audiencia define el estilo
Nuestra API la consumen desarrolladores de RR.HH.[^irs-2025] y fintech que normalmente integran cinco o seis APIs por proyecto. No quieren aprender un nuevo lenguaje de query ni montar resolvers — quieren cURL, fetch, requests. Por eso fuimos con REST clásico: cinco endpoints, JSON simple, OpenAPI 3.1.
Autenticación en el header, no en la URL
Las API keys en query string aparecen en logs, referers y capturas. Pasarlas a `X-API-Key` (con fallback a `Authorization: Bearer`) elimina la mayoría del leak sin complicar al desarrollador.
Cuotas rolling de 30 días, no calendario
Elegimos rolling porque el calendario crea picos artificiales a principio de mes. La ventana se renueva cuando la petición más antigua sale de los últimos 30 días.
Free tier suficiente para validar valor
1.000 peticiones por ventana cubren prototipo, hackathon o equipo de 10 personas. Por encima esperamos conversación humana.
Hash de integridad en el recibo
El endpoint `POST /receipt` devuelve un SHA-256 de los campos de entrada. Auditores pueden recalcular y comparar — cualquier alteración del PDF se detecta al instante.
OpenAPI antes del código
Diseñamos la OpenAPI primero, generamos types TypeScript de ahí y luego escribimos los handlers. La documentación nunca queda desactualizada — es el contrato.
Lo que quedó fuera (por ahora)
Webhooks, batch endpoints y multi-stop con optimización de ruta. Cada release aparecerá en el [changelog público](/api/changelog) con RSS.