Metodología de la API

Cada conversión que Convertitive publica es también un endpoint JSON bajo /api/v1/. La API ha estado activa desde FAZ 4 y sirve los mismos factores y fórmulas que la interfaz de usuario: si un resultado es correcto en la página, es correcto desde la API.

Diseño de endpoints

Estilo REST. La ruta describe el recurso; la cadena de consulta lleva los parámetros. Ejemplos:

• GET /api/v1/convert/unit?category=length&from=cm&to=inches&value=5
• GET /api/v1/convert/currency?from=USD&to=EUR&value=100
• GET /api/v1/convert/color?from=hex&to=rgb&value=%23FF6B35
• GET /api/v1/categories — lista todas las categorías de unidades
• GET /api/v1/health/ — estado del servicio (uptime + versión)

Sin cuerpos POST. Todas las entradas son parámetros de consulta. Idempotente, almacenable en caché y compatible con el navegador.

Envolvente de respuesta

Cada respuesta exitosa usa la misma estructura:

{
  "ok": true,
  "data": { /* específico del endpoint */ },
  "meta": { /* metadatos opcionales: rateDate, factor, etc. */ }
}

Cada respuesta de error:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAM",
    "message": "Explicación legible por humanos",
    "param": "from"
  }
}

Códigos de estado HTTP estándar: 200 para éxito, 400 para errores de entrada, 404 para categorías/unidades desconocidas, 500 solo cuando algo realmente se rompió. No trate los errores 4xx como reintentables.

Política CORS

Access-Control-Allow-Origin: * en cada endpoint de la API. Úselo desde cualquier origen, incluyendo el desarrollo en localhost. No se necesita preflight porque cada solicitud es GET sin encabezados personalizados: se aplican las reglas de solicitud simple.

Sin autenticación

Sin clave de API, sin OAuth, sin solicitudes firmadas. Cada endpoint es anónimo. Tres razones:

1. Los datos no son suficientemente valiosos para restringirlos. Los factores de conversión de unidades son de dominio público. Las tasas del BCE son republicadas públicamente por ~20 servicios. Cobrar por ellos sería cobrar por los datos de otro.
2. La autenticación añade fricción al caso de uso dominante. Un desarrollador probando una funcionalidad, un estudiante creando un script de comparación para sus deberes, un aficionado construyendo un rastreador: ninguno de ellos quiere registrarse primero.
3. Los límites de velocidad gestionan el abuso. Los valores predeterminados de Cloudflare más el coste computacional trivial de cada conversión significan que alguien que intente rastrear Convertitive puede obtener los datos más rápidamente reflejando directamente el feed público del BCE.

Versionado

El prefijo /api/v1/ es intencional. Cuando la envolvente de respuesta o la forma del error cambia de manera significativa, se publica un /api/v2/ en paralelo; v1 se admite durante al menos 12 meses después del lanzamiento de v2.

Las correcciones de errores y los cambios aditivos (nuevos endpoints, nuevos campos opcionales en las respuestas) se publican continuamente sin un incremento de versión.

La API en sí es agnóstica al idioma: los números, los símbolos de unidades y los códigos ISO no se traducen, pero las páginas editoriales que la documentan sí. Publicamos variantes localizadas bajo prefijos de ruta por idioma y las señalamos a los motores de búsqueda con anotaciones hreflang generadas desde un registro de traducciones central, para que un lector español de /es/methodology/api/ obtenga el mismo contrato JSON descrito en su idioma.

Actualidad de las tasas de cambio

Los endpoints de divisas devuelven la tasa de mercado medio del BCE almacenada en caché durante una hora mediante ISR. El campo meta.rateDate en cada respuesta de divisas indica cuándo se publicó la tasa (siempre un día hábil reciente del BCE). Para trabajo en tiempo real de alta precisión, obtenga las tasas de su bróker; para cualquier otra cosa, nuestra caché es suficiente.

Qué no añadiremos a la API

• Endpoints POST para operaciones con estado (no tenemos estado).
• Endpoints masivos (itere sobre los individuales; es suficientemente rápido).
• WebSocket / streaming (los datos no cambian con suficiente frecuencia como para justificar el protocolo).
• Claves de API / niveles de pago (véase «sin autenticación» arriba).

Detalles del algoritmo: ciclo de vida de la solicitud de extremo a extremo

Cada solicitud a la API sigue el mismo pipeline de seis etapas para que el comportamiento observable sea uniforme en todos los endpoints. Las etapas, en orden:

1. Enrutamiento en el borde. Cloudflare hace coincidir la solicitud con el mapa de rutas en caché y sirve la respuesta en caché (divisas, pares de unidades populares) o reenvía el fallo a la función de Next.js. Latencia de acierto de caché p50: ~25 ms; fallo de caché p50: ~70 ms.
2. Método y preflight CORS. Rechazar métodos que no sean GET con 405. Aplicar el encabezado Access-Control-Allow-Origin: * en cada respuesta según la especificación Fetch de WHATWG.
3. Validación de esquema. Analizar los parámetros de consulta con un esquema estilo Zod. Los parámetros faltantes o mal formados devuelven 400 con { ok: false, error: { code: "INVALID_PARAM", param } }.
4. Resolver la conversión. Buscar la conversión objetivo en el mismo registro que usa la interfaz de usuario (unidades, divisas, color, imagen …). Para divisas, leer la caché ISR; para unidades/color, la función es un cálculo puro determinista.
5. Formatear la envolvente. Siempre { ok: true, data, meta }. Los números se serializan como números JSON (no como cadenas) según RFC 8259 para el análisis nativo por parte del consumidor.
6. Encabezados de caché. Las respuestas de divisas reciben Cache-Control: public, max-age=3600, stale-while-revalidate=86400; las respuestas de unidades/color reciben max-age=31536000, immutable porque las matemáticas nunca cambian.

Fuentes y referencias

El diseño de la API sigue la semántica HTTP de RFC 9110 y las reglas de almacenamiento en caché HTTP de RFC 9111. El comportamiento CORS sigue la especificación Fetch de WHATWG. Los cuerpos de respuesta usan JSON UTF-8 según RFC 8259. La lógica de la envolvente de errores se remonta a RFC 7807 (Detalles del problema). Véase el bloque de fuentes al pie de la página para las especificaciones canónicas.

Supuestos y limitaciones

• Solo GET. Sin POST/PUT/DELETE. Cualquier cosa que requiera un cuerpo necesitaría un diseño diferente y muy probablemente autenticación.
• Sin análisis del cuerpo de la solicitud.Todas las entradas son parámetros de consulta con codificación URL. Las entradas mayores de ~2 KB corren el riesgo de alcanzar los límites de longitud de URL en intermediarios.
• Los límites de velocidad están en el borde de red, no por clave de API. Los clientes de alto volumen que comparten un NAT pueden compartir la misma cuota; refleje los datos relevantes localmente para cargas de producción.
• Sin SLA. La API es de mejor esfuerzo. Almacene agresivamente en caché y trate los errores 5xx como transitorios.
• Sin WebSocket / SSE estructurado. El sondeo está bien porque los datos subyacentes se actualizan como máximo cada hora.
• Solo JSON, sin XML / msgpack. La negociación Accept no está implementada.
• Marcas de tiempo sin zona horaria en algunas respuestas legadas. Todos los nuevos endpoints emiten ISO 8601 con offset explícito; los campos anteriores a v1.4 son UTC por convención pero carecen del sufijo Z.

Documentación en vivo en /api/.