# 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.

**Autor:** Camila Ribeiro — Editora de Operaciones de Campo  
**Publicado:** 2026-05-02  
**Actualizado:** 2026-05-02  
**URL:** https://kilometraje.co/blog/diseno-de-una-api-publica-las-decisiones-detras-de-nuestro-lanzamiento

**TL;DR:** Por qué elegimos REST en vez de GraphQL, header en vez de query string y cuotas rolling en vez de calendario.

- Nuestra API la consumen desarrolladores de RR.HH.
- Las API keys en query string aparecen en logs, referers y capturas.
- Elegimos rolling porque el calendario crea picos artificiales a principio de mes.
- 1.000 peticiones por ventana cubren prototipo, hackathon o equipo de 10 personas.
- El endpoint POST /receipt devuelve un SHA-256 de los campos de entrada.

## 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.

## Fuentes

- [IRS — Standard Mileage Rates for 2025](https://www.irs.gov/tax-professionals/standard-mileage-rates) — Internal Revenue Service (2026-04-28)