Conectar un custom domain name a tu API en AWS transforma URLs públicas poco amigables en endpoints profesionales y memorables. Aquí aprendes a integrar un dominio personalizado con API Gateway usando el plugin Serverless Domain Manager, ideal si trabajas con arquitecturas serverless y quieres automatizar despliegues.

Por qué usar un custom domain name en API Gateway

Cuando despliegas un API con Serverless Framework, obtienes una URL pública que termina en algo como /dev. Funciona, pero no es amigable ni escalable. Y aquí viene lo interesante: puedes asociar un nombre de dominio propio a tu API y olvidarte de esas URLs largas.

En la consola de AWS, dentro de API Gateway, vas a encontrar tu API (por ejemplo, crud Serverless users) y la sección de stages. Ese stage de dev es solo uno de los posibles ambientes que tu proyecto puede tener.

¿Qué es un stage en API Gateway? Es un ambiente lógico donde se despliega tu API. Los más comunes son dev, QA, staging y producción. Cada uno tiene su propio endpoint y configuración.

Cómo se relacionan los stages con un dominio personalizado

A medida que tu proyecto crece, vas a necesitar múltiples ambientes. Con Serverless Framework puedes manejar esto con variables de entorno y dejarlo transparente para quien consume el API. La pieza clave es enlazar cada stage con un dominio mediante API mappings [02:30].

Cómo crear un API mapping en AWS manualmente

Un API mapping le dice al custom domain name a qué API y stage debe apuntar. Sin esto, acceder al dominio devuelve un mensaje de forbidden porque no hay recurso asociado.

Los pasos en consola son directos:

• Entra a Custom domain names y selecciona tu dominio (por ejemplo, slscourse.platzi.com).
• Ve a API mappings y agrega uno nuevo.
• Selecciona el API y el stage disponible (en este caso, dev).
• Define un path opcional. Si pones api, ese valor reemplaza al dev en la URL final.

Una vez guardado, tu endpoint pasa de una URL larga a algo como slscourse.platzi.com/api/users/1. Mucho más limpio.

Por qué Postman sigue pidiendo autenticación

Aunque el mapping funciona, el API sigue protegido. Si haces la petición sin credenciales, recibes un forbidden. Aquí entra el API key que configuraste antes: agregas un header x-api-key con tu llave y el endpoint responde correctamente.

¿Qué hace un API mapping? Conecta un custom domain name con un API y un stage específicos en API Gateway, permitiendo reemplazar el path del stage por uno personalizado.

Cómo automatizar el dominio con Serverless Domain Manager

Hacer todo esto a mano funciona, pero no escala. El plugin Serverless Domain Manager automatiza la creación del API mapping en cada despliegue.

La instalación es la misma que con cualquier plugin de Serverless:

bash npm install serverless-domain-manager --save-dev

El flag --save-dev lo registra como dependencia de desarrollo, sin afectar tus dependencias de producción [06:45].

Cómo configurar el plugin en serverless.yml

Después de instalar, agrega el plugin en la sección plugins y configura los parámetros dentro de custom, al mismo nivel que tu configuración de DynamoDB:

yaml custom: customDomain: domainName: slscourse.platzi.com stage: dev basePath: mapping endpointType: regional securityPolicy: tls_1_2 apiType: rest

No necesitas certificateName si ya creaste el certificado al configurar el custom domain name, y tampoco hace falta tocar Route 53 si ya está enlazado.

Qué pasa al ejecutar sls deploy

Al correr sls deploy, el plugin se encarga de crear el API mapping automáticamente. La consola muestra una sección extra de Serverless Domain Manager con el domain name, el target domain y el hosted zone ID.

Si revisas la sección de API mappings en AWS, vas a ver un nuevo mapping con el basePath que definiste (en el ejemplo, mapping). Probarlo en Postman es cuestión de cambiar el path en la URL y enviar la petición con tu x-api-key.

¿Para qué sirve Serverless Domain Manager? Es un plugin que automatiza la creación y configuración de custom domain names y API mappings al desplegar con Serverless Framework, eliminando pasos manuales en la consola de AWS.

Buenas prácticas al integrar dominios personalizados

Un dominio personalizado no es solo estética. Es parte de las buenas prácticas cuando integras servicios como Lambda, SQS, S3 y API Gateway en un proyecto serverless. Algunas recomendaciones que salen de esta integración:

• Usa nombres de dominio que reflejen el propósito del proyecto y faciliten la mnemotecnia.
• Mantén un base path coherente entre ambientes (por ejemplo, api para producción, mapping para pruebas).
• Aprovecha las variables de entorno de Serverless Framework para parametrizar el stage y el dominio según el ambiente.
• Protege siempre tus endpoints con API keys o custom authorizers, incluso detrás de un dominio personalizado.

Con esto cierras un flujo completo: integración de servicios, seguridad con API Gateway y acceso profesional mediante un dominio propio. ¿Ya probaste configurar tu propio dominio? Cuéntame en los comentarios qué plugin o configuración te ha funcionado mejor.