Nginx como Router de API Inteligente: Enrutamiento Condicional y Modificación de Cabeceras

Nginx, más allá de ser un simple servidor web o proxy inverso, puede transformarse en un potente router de API inteligente. Esta capacidad es crucial en arquitecturas de microservicios o cuando necesitas una capa flexible para gestionar el tráfico hacia diferentes versiones de APIs, entornos o servicios backend, aplicando lógicas específicas.

En este tutorial, te guiaremos a través de la configuración de Nginx para manejar enrutamiento condicional basado en varios parámetros (como cabeceras, cookies o la URI de la solicitud), modificar cabeceras HTTP para añadir seguridad o información adicional, y utilizar el módulo map para crear reglas de enrutamiento dinámicas y escalables.

🚀 ¿Por qué Nginx como Router de API Inteligente?

La necesidad de un router de API va más allá de un simple proxy. Implica inteligencia en la forma en que se manejan las solicitudes: decidir a dónde enviar el tráfico basándose en criterios específicos, manipular las solicitudes y respuestas en tránsito, y añadir una capa de abstracción entre los clientes y los servicios backend.

Beneficios Clave:

• Flexibilidad en el Enrutamiento: Dirige solicitudes a diferentes servicios o versiones de API basándose en cabeceras, URI, métodos HTTP, etc.
• Seguridad Mejorada: Modifica o añade cabeceras de seguridad, filtra peticiones no deseadas.
• Agregación/Orquestación (parcial): Aunque Nginx no es un orquestador completo, puede simplificar la exposición de múltiples servicios.
• Observabilidad: Añade cabeceras para rastreo o depuración.
• Control de Versiones: Facilita el despliegue de nuevas versiones de APIs sin interrumpir a los clientes existentes.

🛠️ Requisitos Previos

Para seguir este tutorial, necesitarás lo siguiente:

• Un servidor Linux (Ubuntu, CentOS, etc.) con Nginx instalado.
• Conocimientos básicos de la línea de comandos de Linux.
• Familiaridad con la configuración básica de Nginx.
• Acceso sudo o root en el servidor.

Si aún no tienes Nginx instalado, puedes hacerlo fácilmente. Por ejemplo, en Ubuntu:

sudo apt update
sudo apt install nginx

🚦 Enrutamiento Condicional Básico con if

Nginx ofrece la directiva if para tomar decisiones condicionales. Aunque potente, su uso excesivo en la configuración de Nginx puede llevar a problemas de rendimiento y complejidad. Se recomienda usar map para escenarios más complejos o basados en múltiples condiciones.

Consideremos un escenario donde queremos dirigir el tráfico a diferentes backends basándonos en una cabecera HTTP X-API-Version.

Ejemplo: Enrutamiento por Versión de API

Crearemos dos upstreams (grupos de servidores backend) que representarán dos versiones de nuestra API.

# /etc/nginx/nginx.conf o un archivo incluido en conf.d

upstream backend_v1 {
    server 192.168.1.100:8081;
    server 192.168.1.101:8081;
}

upstream backend_v2 {
    server 192.168.1.102:8082;
    server 192.168.1.103:8082;
}

server {
    listen 80;
    server_name api.example.com;

    location /api/ {
        # Por defecto, enrutamos a v1 si la cabecera no está presente o no coincide
        proxy_pass http://backend_v1;

        # Si la cabecera X-API-Version es '2.0', enrutar a v2
        if ($http_x_api_version = "2.0") {
            proxy_pass http://backend_v2;
        }

        # Asegúrate de que todas las cabeceras se pasen correctamente
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Explicación:

1. Definimos dos grupos de servidores backend: backend_v1 y backend_v2.
2. En el bloque location /api/, establecemos un proxy_pass por defecto a backend_v1.
3. La directiva if ($http_x_api_version = "2.0") evalúa la cabecera X-API-Version. Si su valor es "2.0", el proxy_pass se reescribe a backend_v2.

Probando el Enrutamiento Condicional

Para probar esta configuración, guarda el archivo, verifica la sintaxis de Nginx y recarga el servicio:

sudo nginx -t
sudo systemctl reload nginx

Ahora, puedes usar curl para enviar solicitudes con y sin la cabecera X-API-Version:

# Solicitud sin cabecera X-API-Version (debería ir a backend_v1)
curl -H "Host: api.example.com" http://localhost/api/data

# Solicitud con X-API-Version: 2.0 (debería ir a backend_v2)
curl -H "Host: api.example.com" -H "X-API-Version: 2.0" http://localhost/api/data

🗺️ Enrutamiento Avanzado con el Módulo map

El módulo map es una herramienta muy potente en Nginx para crear variables cuyos valores dependen de otras variables de solicitud. Es ideal para escenarios de enrutamiento más complejos y dinámicos, ya que evita los problemas asociados con if.

Sintaxis de map

map $variable_de_origen $variable_de_destino {
    valor1    resultado1;
    valor2    resultado2;
    default   resultado_por_defecto;
}

La directiva map debe colocarse en el contexto http, fuera de cualquier bloque server o location.

Ejemplo: Enrutamiento por Subdominio y URI con map

Imagina que quieres enrutar peticiones a diferentes backends basándose en el subdominio y, para un subdominio específico, también por la URI.

Primero, definamos nuestros upstreams:

# /etc/nginx/nginx.conf o un archivo incluido

upstream api_service_users {
    server 192.168.1.104:8080;
}

upstream api_service_products {
    server 192.168.1.105:8081;
}

upstream api_service_legacy {
    server 192.168.1.106:8082;
}

upstream default_backend {
    server 192.168.1.107:9000;
}

map $host $api_backend {
    users.api.example.com   api_service_users;
    products.api.example.com  api_service_products;
    legacy.api.example.com    api_service_legacy;
    default                   default_backend;
}

server {
    listen 80;
    server_name ~^(?<subdomain>[^\.]+)\.api\.example\.com$;

    location / {
        proxy_pass http://$api_backend;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Explicación:

1. El bloque map $host $api_backend crea una nueva variable $api_backend. Su valor dependerá del $host (el nombre de dominio de la solicitud).
2. Si el Host es users.api.example.com, $api_backend será api_service_users, y así sucesivamente.
3. default establece un valor predeterminado si no hay coincidencia.
4. En el bloque server, usamos una expresión regular en server_name para capturar el subdominio (aunque no lo usamos directamente en este map, es útil para otros escenarios).
5. proxy_pass http://$api_backend; utiliza la variable dinámica para dirigir la solicitud al upstream correcto.

Enrutamiento por Prefijo de URI con map

Ahora, combinemos el enrutamiento basado en la URI. Supongamos que dentro del legacy.api.example.com, queremos que /v1/ vaya a un backend antiguo y /v2/ a uno nuevo.

# /etc/nginx/nginx.conf o un archivo incluido

# ... (upstreams existentes)

upstream api_legacy_v1 {
    server 192.168.1.106:8082;
}

upstream api_legacy_v2 {
    server 192.168.1.108:8083;
}

# Este map determinará el backend para el subdominio 'legacy'
map $request_uri $legacy_api_backend {
    ~^/v1/    api_legacy_v1;
    ~^/v2/    api_legacy_v2;
    default   api_legacy_v1; # Por defecto, si no es v2, va a v1
}

map $host $api_backend {
    users.api.example.com   api_service_users;
    products.api.example.com  api_service_products;
    legacy.api.example.com    $legacy_api_backend; # Ahora usa la variable del otro map
    default                   default_backend;
}

server {
    listen 80;
    server_name ~^(?<subdomain>[^\.]+)\.api\.example\.com$;

    location / {
        proxy_pass http://$api_backend;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

En este ejemplo:

1. Hemos introducido un segundo map llamado $legacy_api_backend que decide el backend basándose en la $request_uri (la ruta de la URL) usando expresiones regulares (~^/v1/).
2. El map $host $api_backend ahora apunta a $legacy_api_backend cuando el host es legacy.api.example.com.

Este encadenamiento de maps ofrece una flexibilidad increíble para construir lógicas de enrutamiento complejas y limpias.

🛡️ Modificación de Cabeceras HTTP

Nginx permite manipular tanto las cabeceras de solicitud enviadas al backend (proxy_set_header) como las cabeceras de respuesta recibidas del backend (add_header, expires). Esto es fundamental para añadir seguridad, información de rastreo, o simplemente limpiar las cabeceras.

Modificando Cabeceras de Solicitud (al backend)

Ya hemos visto proxy_set_header en los ejemplos anteriores. Es crucial para pasar información relevante del cliente al backend. Algunos usos comunes:

• proxy_set_header Host $host;: Pasa el nombre de host original de la solicitud.
• proxy_set_header X-Real-IP $remote_addr;: Envía la dirección IP real del cliente.
• proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;: Un estándar para pasar la cadena de IPs de proxies intermedios.
• proxy_set_header X-Forwarded-Proto $scheme;: Indica si la solicitud original fue HTTP o HTTPS.

Podemos también añadir cabeceras personalizadas. Por ejemplo, para indicar que la solicitud pasó por un gateway Nginx:

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://default_backend;
        proxy_set_header X-Nginx-Gateway "true";
        proxy_set_header X-Request-ID $request_id; # Genera un ID único por solicitud
        # ... otras cabeceras proxy_set_header
    }
}

La variable $request_id (disponible desde Nginx 1.11.0) es muy útil para el rastreo de solicitudes a través de múltiples servicios.

Modificando Cabeceras de Respuesta (al cliente)

Las directivas add_header y expires se usan para modificar las cabeceras que Nginx envía de vuelta al cliente.

Añadiendo Cabeceras de Seguridad

Es una buena práctica añadir cabeceras de seguridad para proteger a los clientes contra ataques comunes.

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://default_backend;

        # Cabeceras de seguridad
        add_header X-Frame-Options "DENY" always; # Previene Clickjacking
        add_header X-Content-Type-Options "nosniff" always; # Evita la "adivinación" de tipos MIME
        add_header X-XSS-Protection "1; mode=block" always; # Protege contra ataques XSS
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always; # HSTS
        add_header Referrer-Policy "no-referrer-when-downgrade" always; # Controla el envío de Referrer

        # ... otras configuraciones
    }
}

La palabra clave always después de add_header asegura que la cabecera se añada a todas las respuestas, incluso a las de error.

Cache-Control y Expires

Para controlar el caching en el lado del cliente o de proxies intermedios, puedes usar expires o add_header Cache-Control.

server {
    listen 80;
    server_name api.example.com;

    location /public/static/ {
        # Los archivos estáticos se cachean por 7 días
        expires 7d;
        add_header Cache-Control "public, max-age=604800";
        root /var/www/html;
    }

    location /api/ {
        proxy_pass http://default_backend;
        # Para APIs, no queremos caché del lado del cliente por defecto
        add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0" always;
        expires off;
        # ... otras configuraciones
    }
}

📊 Escenario Práctico: Enrutamiento de API Basado en Entorno

Imaginemos que tenemos una API que se despliega en dos entornos: dev y prod. Queremos que Nginx enrute las solicitudes a estos entornos basándose en una cabecera personalizada X-Environment.

🎯 Diseño del Enrutamiento

1. Backend Dev: dev.api.example.com -> upstream dev_api_servers
2. Backend Prod: prod.api.example.com -> upstream prod_api_servers
3. Default: Si no se especifica la cabecera, o si el host no coincide, ir a prod.

Configuración de Nginx

# /etc/nginx/nginx.conf o un archivo separado en /etc/nginx/conf.d/api-router.conf

# Define los backends (upstreams) para cada entorno
upstream dev_api_servers {
    server 10.0.0.10:8000;
    server 10.0.0.11:8000;
}

upstream prod_api_servers {
    server 10.0.0.20:8000;
    server 10.0.0.21:8000;
}

# Usa map para determinar el backend basado en el host y, potencialmente, en otras cabeceras
map $host $environment_backend {
    default              prod_api_servers; # Por defecto, va a producción
    dev.api.example.com  dev_api_servers;
    prod.api.example.com prod_api_servers;
}

# Puedes usar otro map para decisiones más finas basadas en cabeceras, si el host es genérico
# Por ejemplo, si un solo host 'api.example.com' debe rutear basado en 'X-Environment'
map $http_x_environment $api_version_backend {
    dev   dev_api_servers;
    prod  prod_api_servers;
    default prod_api_servers;
}

server {
    listen 80;
    server_name api.example.com dev.api.example.com prod.api.example.com;

    # Redirecciona HTTP a HTTPS si tienes SSL configurado
    # return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name api.example.com dev.api.example.com prod.api.example.com;

    # ... Configuración SSL (certificados, ciphers, etc.)

    location / {
        # Priorizamos el enrutamiento por subdominio (via $environment_backend)
        # Si el subdominio no coincide, o es 'api.example.com', podemos usar X-Environment
        set $target_backend $environment_backend;

        # Si el host es el genérico 'api.example.com', entonces usa la cabecera X-Environment
        if ($host = "api.example.com") {
            set $target_backend $api_version_backend;
        }

        proxy_pass http://$target_backend;

        # Cabeceras de solicitud
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Environment-Routed "true"; # Para rastreo

        # Cabeceras de respuesta
        add_header X-Frame-Options "DENY" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-XSS-Protection "1; mode=block" always;
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
        add_header Referrer-Policy "no-referrer-when-downgrade" always;

        # Desactivar caché por defecto para la API
        add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0" always;
        expires off;
    }
}

Observaciones de la Configuración:

• Hemos combinado el enrutamiento por host y por cabecera X-Environment para ofrecer una solución más robusta.
• La variable $target_backend se inicializa con el valor del map $host. Luego, un if la sobrescribe si el host es el dominio principal (api.example.com) y se detecta una cabecera X-Environment.
• Las cabeceras de seguridad y caché se aplican consistentemente a todas las solicitudes de API.

Probando el Enrutamiento de Entornos

1. Solicitud a dev.api.example.com (debe ir a dev_api_servers):

curl -H "Host: dev.api.example.com" http://localhost/data

2. Solicitud a prod.api.example.com (debe ir a prod_api_servers):

curl -H "Host: prod.api.example.com" http://localhost/data

3. Solicitud a api.example.com con X-Environment: dev (debe ir a dev_api_servers):

curl -H "Host: api.example.com" -H "X-Environment: dev" http://localhost/data

4. Solicitud a api.example.com sin cabecera X-Environment (debe ir a prod_api_servers por defecto):

curl -H "Host: api.example.com" http://localhost/data

🔍 Consideraciones Avanzadas

Variables Nginx Útiles

Nginx expone una gran cantidad de variables predefinidas que pueden ser utilizadas en map e if:

# /etc/nginx/nginx.conf

upstream old_feature_backend {
    server 10.0.0.30:8000;
}

upstream new_feature_backend {
    server 10.0.0.31:8000;
}

map $cookie_ab_test_group $feature_backend {
    A       old_feature_backend;
    B       new_feature_backend;
    default old_feature_backend;
}

server {
    listen 80;
    server_name myapp.example.com;

    location /feature-test/ {
        proxy_pass http://$feature_backend;
        proxy_set_header Host $host;
        # ... otras cabeceras
    }
}

Logging Mejorado para Depuración

Para depurar el enrutamiento, es muy útil añadir variables a los logs de acceso de Nginx.

log_format custom_api '$remote_addr - $remote_user [$time_local] ' 
                      '"$request" $status $body_bytes_sent ' 
                      '"$http_referer" "$http_user_agent" ' 
                      '"$http_x_api_version" "$api_backend" ' 
                      '"$target_backend"';

server {
    listen 80;
    server_name api.example.com;

    access_log /var/log/nginx/api-access.log custom_api;
    error_log /var/log/nginx/api-error.log warn;

    # ... configuración del router de API
}

Aquí, hemos añadido $http_x_api_version, $api_backend, y $target_backend a nuestro formato de log. Esto nos permitirá ver exactamente qué valores tenían estas variables y a qué backend se enrutó la solicitud.

✅ Conclusión

Nginx es una herramienta increíblemente flexible y potente que puede ir mucho más allá de ser un simple proxy. Al aprovechar sus directivas map, if (con precaución), y la capacidad de manipular cabeceras, puedes construir un router de API inteligente y robusto que gestionará tu tráfico de manera eficiente, segura y escalable.

Dominar estas técnicas te permitirá crear arquitecturas más dinámicas, facilitar el versionado de APIs, implementar pruebas A/B, y aplicar políticas de seguridad de manera centralizada. ¡Ahora tienes las herramientas para llevar tu gestión de APIs al siguiente nivel con Nginx!