Conectar un nombre de dominio personalizado a tu API desplegada en AWS transforma por completo la experiencia de acceso a tus recursos. En lugar de compartir URLs públicas largas y poco memorables, puedes ofrecer rutas limpias y profesionales como slscourse.platzi.com/mapping/users/1. Este paso cierra la integración completa de un proyecto serverless que ya incluye SQS, Lambda, buckets en S3, API Gateway, Custom Authorizer y API Keys.
¿Qué es un Custom Domain Name en API Gateway?
Un Custom Domain Name es un nombre de dominio propio que se asocia directamente a tu API en API Gateway. Cuando despliegas con Serverless Framework, la URL generada termina en algo como /dev, lo cual no resulta amigable ni profesional. Al configurar un dominio personalizado, reemplazas esa ruta por una que refleje tu proyecto o tu marca.
Dentro de la consola de AWS, al ingresar a API Gateway > Custom Domain Names, puedes ver los dominios que ya están creados. Sin embargo, un dominio recién configurado responde con un message forbidden si no se ha vinculado correctamente a un API ni se han enviado los parámetros de autenticación necesarios.
¿Cómo funcionan los API mappings?
Los API mappings son la pieza que conecta tu Custom Domain Name con una API y un stage específico. Al configurar un mapping, le indicas al dominio personalizado a qué API debe apuntar y bajo qué ruta base (base path) [4:42].
- Seleccionas la API desplegada y el stage correspondiente (por ejemplo,
dev).
- Defines un path opcional que reemplaza el stage en la URL final.
- Si defines
api como path, la ruta cambia de /dev/users a /api/users.
Esto permite que, cuando tu proyecto crezca y manejes múltiples ambientes como QA, staging o producción, cada stage pueda tener su propio mapping bajo el mismo dominio.
¿Cómo se valida el acceso con API Key?
Al acceder al recurso desde el navegador o desde Postman, el endpoint sigue protegido por API Gateway. Si intentas consultar /api/users/1 sin credenciales, recibirás un error de forbidden o unauthorized [6:18].
Para autenticarte correctamente:
- Agrega el header
x-api-key en tu petición.
- Copia el valor del API Key que configuraste previamente.
- Envía la solicitud y confirma que recibes la respuesta esperada.
¿Cómo automatizar la configuración con Serverless Domain Manager?
El plugin Serverless Domain Manager permite gestionar toda la configuración de Custom Domain Names y API mappings de forma automática, directamente desde el archivo serverless.yml, sin necesidad de hacer clics manuales en la consola de AWS [7:25].
La instalación se realiza con:
bash
npm install serverless-domain-manager --save-dev
El flag --save-dev asegura que se registre como dependencia de desarrollo, manteniendo separadas las dependencias de producción.
Después de instalar, se agrega serverless-domain-manager en la sección de plugins del archivo serverless.yml. La configuración principal va dentro de la sección custom, al mismo nivel que otras configuraciones como DynamoDB [9:03]:
yaml
custom:
customDomain:
domainName: slscourse.platzi.com
stage: dev
basePath: mapping
endpointType: regional
securityPolicy: tls_1_2
apiType: rest
- domainName: el dominio personalizado asociado.
- stage: el ambiente al que apunta.
- basePath: la ruta base que reemplaza al stage en la URL.
- endpointType, securityPolicy y apiType: detalles que puedes consultar en la configuración del Custom Domain Name y del tipo de API Gateway.
¿Qué sucede después del despliegue?
Al ejecutar sls deploy, el framework crea automáticamente el API mapping y muestra una nueva sección en la salida de consola llamada Serverless Domain Manager [10:30]. Esta sección incluye:
- El nombre de dominio configurado.
- El target domain que AWS genera internamente.
- El hosted zone ID asociado.
Para validar, basta ir a la sección de API mappings en la consola de AWS, donde aparecerá el nuevo mapping con el base path definido. Desde Postman, reemplazas la ruta anterior por el nuevo base path y confirmas que la respuesta es correcta.
¿Por qué usar dominios personalizados en proyectos serverless?
Utilizar nombres de dominio personalizados es una buena práctica que mejora la nemotecnia de tus recursos y facilita la gestión cuando el proyecto escala. En lugar de depender de URLs generadas automáticamente por AWS, ofreces rutas claras y consistentes que se adaptan a distintos ambientes sin cambiar la lógica del proyecto.
Si ya integraste Lambda, SQS, S3, Custom Authorizer y API Keys, agregar un dominio personalizado con Serverless Domain Manager es el paso natural para profesionalizar tu arquitectura. Comparte en los comentarios cómo planeas aplicar esta configuración en tus propios proyectos.
