Guía de uso de CorsAPI — para tu aplicación y tu infraestructura

CorsAPI se sitúa entre tu frontend (o cualquier cliente HTTP) y APIs HTTP de terceros. Aplica las reglas CORS que defines, valida la URL contra listas de hosts y prefijos de ruta, identifica el proyecto con una clave API y aplica cuotas por minuto. No es un proxy abierto: solo se pueden alcanzar hosts y rutas que hayas permitido explícitamente.

Tú alojas el backend y la base de datos. En el panel creas proyectos, añades orígenes del navegador, listas de hosts de subida (con comodines opcionales), prefijos de ruta y claves API. Los mismos conceptos valen para curl, fetch en React o WebView móvil; solo las llamadas desde navegador exigen Origin y cabeceras CORS correctas.

Tras registrarte trabajas en el panel. El proyecto agrupa reglas del proxy, claves API y contadores de cuota. Las organizaciones son opcionales y útiles para equipos y roles. Un solo proyecto basta para empezar; puedes separar staging y producción más adelante.

Cada petición proxificada se atribuye al proyecto de la clave que envías. Al rotar una clave en el panel, el secreto anterior deja de valer para peticiones nuevas; planifica solapes breves si necesitas despliegues sin cortes.

Tras iniciar sesión abres el espacio de trabajo y eliges un proyecto. En un solo lugar mantienes: orígenes del navegador permitidos, reglas de hosts de subida, prefijos de ruta opcionales, límite por minuto y claves API. Si algo falla, cambia una variable cada vez: si el navegador muestra CORS, revisa orígenes primero; si el proxy devuelve 400, revisa host/path y codificación de URL antes de culpar al proveedor.

Crea claves con nombre por entorno (por ejemplo desarrollo frente a producción) para revocar una sin tumbar la otra. Los resúmenes de uso ayudan a ver si los picos vienen de una clave o de un upstream. Trata las claves como contraseñas: no las pegues en tickets públicos ni documentos compartidos; rota en cuanto haya riesgo de fuga.

La configuración del proyecto es el contrato entre tu aplicación y el proxy: mantén una nota interna de qué hosts y rutas están aprobados por release y revísala cuando un proveedor cambie URLs base o deprecación.

Los navegadores envían la cabecera Origin en XHR/fetch entre orígenes. CorsAPI la compara con la lista del proyecto. Cada línea debe ser un origen completo: esquema + host + puerto (p. ej. http://localhost:5173). http y https son orígenes distintos.

En local suele haber varios puertos; añade todos. Los despliegues preview (Vercel/Netlify) tienen subdominios únicos: añádelos al probar. Si falta un origen, el navegador mostrará error CORS aunque el proxy pudiera alcanzar el upstream.

Las reglas de host indican a qué nombres DNS puede llamar el proxy. Ejemplos: api.github.com. *.midominio.com coincide con un nivel (api.sí; a.b.no). Mantén la lista lo más estrecha posible.

Si el host no está permitido, la petición se rechaza antes de salir de tu red, evitando comportamiento de proxy abierto y errores de tipeo que apunten a dominios inesperados.

Si dejas las rutas vacías para un host, se permiten todas las rutas (dentro de otros límites). Con prefijos como /v1/, solo pasan URLs cuyo path empiece por uno de ellos. Útil cuando la API es grande pero tu producto solo usa unas rutas.

Combina host + ruta cuando varios servicios comparten dominio. En caso de duda, empieza restrictivo y afloja según los logs.

Cada proyecto tiene al menos una clave secreta. Envíala en cada petición al proxy como X-CorsAPI-Key: <secreto> o Authorization: Bearer <secreto>. El backend valida la clave, carga las reglas y reenvía a la URL upstream (consulta OpenAPI para parámetros exactos).

En el servidor usa variables de entorno para no empaquetar la clave en el frontend. En el navegador la clave es visible: trata el proyecto como superficie pública, restringe hosts, rutas y cuotas, y no enrutes APIs internas con la misma clave.

Usa curl para validar conectividad antes de depurar fetch. Sustituye YOUR_SECRET por una clave del panel y codifica la URL de destino. 200 con cuerpo confirma reglas, clave y red. 401 suele ser clave incorrecta o revocada; 400 a menudo codificación o lista de permisos.

Guarda ejemplos curl en runbooks para reproducir incidencias sin el build del frontend.

Desde tu SPA llama a la base URL de CorsAPI que tu equipo configuró para ese entorno (por ejemplo el mismo host que la API de tu app, o un subdominio dedicado), con la ruta del proxy y las cabeceras de clave. El navegador debe ejecutarse en un origen listado en el proyecto. Usa mode: 'cors'.

No mezcles la clave del proxy con las cookies de sesión de tu propia aplicación: son mecanismos distintos.

En Node o funciones sin servidor guarda la clave en secretos y llama como con curl. Ideal para cron, webhooks o cuando el upstream solo debe ver IPs de tu datacenter. Sigues teniendo cuotas y trazabilidad centralizadas.

Al escalar horizontalmente, varias instancias comparten la misma ventana por minuto: dimensiona para picos.

Cualquier producto que permita cabeceras HTTP personalizadas puede usar el proxy — clientes REST, automatización low-code, trabajos programados o apps móviles nativas. Apunta la herramienta a tu base URL de CorsAPI, usa la ruta y parámetros del proxy descritos en la referencia publicada, pasa la URL de destino como indique el contrato y envía X-CorsAPI-Key o Authorization: Bearer con el secreto del proyecto.

En clientes de escritorio (por ejemplo Postman o Insomnia) guarda la base URL y la clave en variables de entorno o de colección para no reescribir secretos. Repite la misma petición con curl para aislar si el fallo es la herramienta, TLS o las reglas del proxy.

Las plataformas con paso HTTP permiten método, URL y cabeceras. Copia la URL del proxy exactamente como en los ejemplos; algunas UIs codifican la query automáticamente — evita doble codificación. En trabajos por cron respeta la cuota por minuto espaciando llamadas o agrupando trabajo en tu lado.

No incrustes secretos de producción en colecciones públicas, snippets compartidos o código que no controlas. Para demos usa un proyecto desechable con hosts muy acotados y límites bajos.

Las respuestas exitosas suelen incluir pistas X-RateLimit-* (nombres según tu despliegue). Reflejan el presupuesto por minuto del proyecto. Úsalas para frenar antes del error duro.

Si se agota la ventana, recibirás 429. Aplica backoff exponencial con jitter y muestra en la UI límites de producto, no solo fallos de red.

400: URL mal formada, validación o host/ruta no permitidos. 401: clave ausente o inválida, u sesión de panel inválida en rutas de UI. 429: cuota. 502/504: fallo o timeout del upstream.

Si tienes IDs de correlación en logs, cruza con el panel para ver si el error se agrupa por upstream o por clave.

Iniciar sesión en la web guarda tokens en cookies httpOnly para el panel. Es independiente de las claves API del proxy. Cerrar sesión no rota claves de proyecto salvo que lo hagas en ajustes.

Para automatización usa claves API y health checks, no scraping del panel.

GET /api/health/live comprueba que el proceso responde; /api/health/ready incluye la base de datos; /api/health es más completo. Conéctalos a probes de Kubernetes o health checks del balanceador.

No expongas detalles sensibles de salud públicamente sin autenticación si tu modelo de amenaza lo requiere.

GET /api/plan/limits devuelve los topes activos del plan gratuito actual, sin autenticación. Úsalo para mostrar límites en herramientas internas o validar la configuración tras un despliegue.

La documentación interactiva puede estar en /api/docs cuando tu despliegue la expone. En producción restringe esa URL (por ejemplo acceso de red o autenticación) para que la superficie no sea enumerable en abierto. Usa el esquema publicado para confirmar nombres de parámetros del proxy.