Conectando con la API de Akua

La API de Akua es un servicio basado en principios REST sobre HTTP y está alojada en infraestructura en la nube. Para garantizar una integración estable y sin interrupciones, los clientes deben seguir ciertas recomendaciones de conectividad, seguridad y manejo de respuestas.

Conectividad

Optimización Global con Cloudflare

Los endpoints públicos de la API de Akua están protegidos y optimizados a través de Cloudflare, lo que proporciona una red de distribución global con baja latencia y alta disponibilidad. Gracias a esto, nuestros clientes pueden acceder a la API con tiempos de respuesta óptimos desde cualquier ubicación geográfica.

Sistema de Nombres de Dominio (DNS)

Dado que nuestros servidores están en la nube y pueden cambiar de dirección IP, Akua no garantiza direcciones IP estáticas. Para evitar problemas de conectividad, recomendamos:

✅ Siempre utilizar el dominio DNS para resolver la dirección IP del servidor de la API.
❌ No utilizar direcciones IP fijas en la configuración de la integración.
🔄 Respetar el tiempo de vida (TTL) de los registros DNS para evitar problemas de caché.

Seguridad y Certificados

La API de Akua establece conexiones seguras mediante TLS (Transport Layer Security). Para garantizar la integridad y seguridad de la comunicación, los clientes deben:

Validar los certificados SSL asegurándose de que la cadena de certificación sea válida.
Verificar que el certificado es emitido por una Autoridad Certificadora (CA) confiable.
Soportar los siguientes protocolos y cifrados recomendados:

TLS 1.3 (recomendado)

TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256

TLS 1.2 (mínimo requerido)

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

🔹 No se admite el pinning de certificados, ya que estos pueden rotar en cualquier momento.

⚠️ Versiones anteriores de TLS (1.0 y 1.1) no son soportadas por razones de seguridad.

⚠️ HTTP (sin cifrado) no es soportado, todas las conexiones deben realizarse mediante HTTPS.

Para más información sobre nuestras prácticas de seguridad y cumplimiento, visite:
https://docs.akua.la/docs/seguridad-y-cumplimiento-en-akua

Control de Tasa (Rate Limiting)

Para garantizar la estabilidad y disponibilidad del servicio para todos los clientes, la API de Akua implementa límites de tasa:

Límite estándar: 1000 solicitudes cada 10 segundos por cliente.
En caso de exceder este límite, la API responderá con un código HTTP 429 (Too Many Requests).
El encabezado de respuesta Retry-After indicará el tiempo en segundos que debe esperar antes de realizar nuevas solicitudes.

Recomendaciones para manejar rate limiting:

Implementar lógica de reintentos con retroceso exponencial
Distribuir solicitudes a lo largo del tiempo cuando sea posible
Monitorear el uso de la API para evitar alcanzar los límites

Protocolo y Estándares HTTP

Para garantizar la compatibilidad y estabilidad, la API de Akua sigue los estándares de HTTP. Los clientes deben asegurarse de:

✅ Usar correctamente los métodos HTTP, como GET, POST, PUT, PATCH y DELETE.
✅ Manejar adecuadamente los códigos de respuesta, como 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized.
✅ Formatear correctamente los encabezados en cada solicitud (Content-Type, Accept, Authorization).

Timeouts

Para evitar tiempos de espera indefinidos y mejorar la experiencia del usuario, recomendamos:

Establecer un timeout de conexión de 5-10 segundos para evitar bloqueos en caso de fallos de red.
Definir un timeout para lectura de respuestas de hasta 20 segundos.
Implementar reintentos con backoff exponencial y jitter para prevenir sobrecarga en la API.

Si una solicitud excede el tiempo máximo de espera, el servidor responderá con un HTTP 504 Gateway Timeout.

Manejo de JSON / Payloads

Para una integración robusta y segura, los clientes deben seguir las mejores prácticas en el manejo de respuestas JSON:

✅ Utilizar un parser JSON estándar que cumpla con RFC 8259.
✅ No asumir un orden específico en los campos JSON, ya que este puede cambiar sin previo aviso.
✅ Ignorar espacios en blanco insignificantes y manejar correctamente caracteres especiales como comillas y barras invertidas.
✅ Utilizar UTF-8 para la codificación de datos.
✅ Aceptar propiedades adicionales en los payloads JSON, ya que nuevas propiedades pueden ser agregadas en el futuro.

⚠️ Evita depender de propiedades marcadas como EXPERIMENTAL en la documentación, ya que estas pueden cambiar o eliminarse sin previo aviso.