Implemente el control de versiones de API basado en rutas mediante dominios personalizados en Amazon API Gateway

PDF

Creado por Corey Schnedl (AWS), Anbazhagan Ponnuswamy (AWS), Marcelo Barbosa (AWS), Gaurav Samudra (AWS), Mario López Martínez (AWS) y Abhilash Vinod (AWS)

Resumen

Este patrón demuestra cómo puede utilizar la función de mapeo de API de dominios personalizados para implementar una solución de control de versiones de API basada en rutas para Amazon API Gateway.

Amazon API Gateway es un servicio totalmente gestionado que puede utilizar para crear, publicar, mantener, supervisar y proteger APIs a cualquier escala. Al utilizar la función de dominio personalizado del servicio, puede crear nombres de dominio personalizados que sean más sencillos e intuitivos y URLs que pueda proporcionarlos a los usuarios de su API. Puedes usar las asignaciones de API para conectar las etapas de la API a un nombre de dominio personalizado. Después de crear un nombre de dominio y configurar los registros de DNS, utiliza las asignaciones de API para enviarle tráfico a APIs través de su nombre de dominio personalizado.

Una vez que una API pasa a estar disponible públicamente, los consumidores la utilizan. A medida que evoluciona una API pública, su contrato de servicio también evoluciona para reflejar las nuevas funciones y capacidades. Sin embargo, no es aconsejable cambiar o eliminar las funciones existentes. Cualquier cambio importante podría afectar a las aplicaciones del consumidor y estropearlas durante el tiempo de ejecución. El control de versiones de las API es importante para evitar que se rompa la compatibilidad con versiones anteriores y se rompa un contrato.

Se necesita una estrategia clara de control de versiones de las API para ayudar a los consumidores a adoptarlas. El control de versiones APIs mediante rutas URLs es el enfoque más sencillo y utilizado con más frecuencia. En este tipo de control de versiones, las versiones se definen explícitamente como parte de la API. URIs El siguiente ejemplo URLs muestra cómo un consumidor puede usar el URI para especificar una versión de API para su solicitud:

https://api.example.com/api/v1/orders

https://api.example.com/api/v2/orders

https://api.example.com/api/vX/orders

Este patrón lo utiliza AWS Cloud Development Kit (AWS CDK) para crear, implementar y probar un ejemplo de implementación de una solución de control de versiones escalable basada en rutas para su API. AWS CDK es un marco de desarrollo de software de código abierto para modelar y aprovisionar los recursos de sus aplicaciones en la nube mediante lenguajes de programación conocidos.

Requisitos previos y limitaciones

Requisitos previos

• Un activo Cuenta de AWS.

• Se requiere la propiedad de un dominio para usar el repositorio de muestras de este patrón y para usar la funcionalidad de dominio personalizada de Amazon API Gateway. Puede usar Amazon Route 53 para crear y administrar los dominios de su organización. Para obtener información sobre cómo registrar o transferir un dominio con Route 53, consulte Registrar nuevos dominios en la documentación de Route 53.

• Antes de configurar un nombre de dominio personalizado para una API, debe tener listo un certificado SSL/TLS. AWS Certificate Manager

• Debe crear o actualizar el registro de recursos del proveedor de DNS para asignarlo al punto de conexión de la API. Sin este mapeo, las solicitudes de API vinculadas al nombre de dominio personalizado no pueden llegar a API Gateway.

Limitaciones

• Los nombres de dominio personalizados no son compatibles con los dominios privados APIs.

• Un nombre de dominio personalizado debe ser único dentro de un Región de AWS todo Cuentas de AWS.

• Para configurar asignaciones de la API con varios niveles, debe usar un nombre de dominio personalizado regional y usar la política de seguridad de TLS 1.2.

• En un mapeo de API, el nombre de dominio personalizado y el mapeado APIs deben estar en el mismo Cuenta de AWS lugar.

• Las asignaciones de API deben contener solo letras, números y los siguientes caracteres: $-_.+!*'()/

• La longitud máxima de la ruta en un mapeo de la API es de 300 caracteres.

• Puede tener 200 mapeos de la API con varios niveles para cada nombre de dominio.

• Solo puede asignar HTTP APIs a un nombre de dominio personalizado regional con la política de seguridad TLS 1.2.

• No puedes asignarlo WebSocket APIs al mismo nombre de dominio personalizado que una API HTTP o una API REST.

• Algunas Servicios de AWS no están disponibles en todas Regiones de AWS. Para ver la disponibilidad regional, consulta AWS Servicios por región. Para conocer puntos de enlace específicos, consulte Puntos de enlace y cuotas del servicio y elija el enlace para el servicio.

Versiones de producto

• Este ejemplo de implementación se utiliza AWS CDK en la TypeScript versión 2.149.0.

Arquitectura

El siguiente diagrama muestra el flujo de trabajo de la arquitectura.

En el siguiente diagrama se ilustra lo siguiente:

1. El usuario de la API envía una solicitud a Amazon API Gateway con un nombre de dominio personalizado.

2. API Gateway enruta dinámicamente la solicitud del usuario a una instancia y etapa adecuadas de API Gateway, según la ruta indicada en la URL de la solicitud. En la siguiente tabla se muestra un ejemplo de cómo se pueden enrutar las distintas rutas basadas en URL a etapas específicas para distintas instancias de API Gateway.

   API	Escenario	Ruta	Punto final predeterminado
   Cálculo APIv1	api	apiv1	Habilitado
   Cálculo APIv2	api	apiv2	Habilitado
   Cálculo X APIv	api	APIvX	Habilitado

3. La instancia de API Gateway de destino procesa la solicitud y devuelve el resultado al usuario.

Automatizar y escalar

Te recomendamos que utilices AWS CloudFormation pilas independientes para cada versión de tu API. Con este enfoque, puedes tener un aislamiento total entre el backend al APIs que se puede enrutar mediante la función de mapeo de API de dominio personalizado. Una ventaja de este enfoque es que se pueden implementar o eliminar diferentes versiones de la API de forma independiente sin que ello suponga el riesgo de modificar otra API. Este enfoque aumenta la resiliencia mediante el aislamiento de las CloudFormation pilas. Además, le proporciona diferentes opciones de back-end para su API AWS Lambda AWS Fargate, como los puntos finales HTTP y las acciones de. Servicios de AWS

Puedes usar estrategias de ramificación de Git, como Gitflow, en combinación con CloudFormation pilas aisladas para administrar el código fuente que se implementa en las diferentes versiones de la API. Al usar esta opción, puedes mantener diferentes versiones de tu API sin necesidad de duplicar el código fuente para las nuevas versiones. Con Gitflow, puedes añadir etiquetas a las confirmaciones dentro de tu repositorio de git a medida que se vayan realizando las versiones. Como resultado, tienes una instantánea completa del código fuente relacionado con una versión específica. A medida que sea necesario realizar actualizaciones, puedes extraer el código de una versión específica, realizar actualizaciones y, a continuación, implementar el código fuente actualizado en la CloudFormation pila que se ajuste a la versión principal correspondiente. Este enfoque reduce el riesgo de interrumpir otra versión de la API, ya que cada versión de la API tiene un código fuente aislado y se implementa en CloudFormation pilas independientes.

Herramientas

Servicios de AWS

• Amazon API Gateway le ayuda a crear, publicar, mantener, supervisar y proteger REST, HTTP y WebSocket APIs a cualquier escala.

• AWS Certificate Manager (ACM) le ayuda a crear, almacenar y renovar claves y certificados SSL/TLS X.509 públicos y privados que protegen sus sitios web y aplicaciones. AWS

• AWS Cloud Development Kit (AWS CDK)es un marco de desarrollo de software de código abierto para definir su infraestructura de nube en código y aprovisionarla mediante ella. AWS CloudFormationEl ejemplo de implementación de este patrón utiliza el AWS CDK in. TypeScript Para trabajar con AWS CDK in se TypeScript utilizan herramientas conocidas, como el TypeScript compilador de Microsoft (tsc), Node.js y el administrador de paquetes de nodos (npm). Si lo prefieres, puedes usar Yarn, aunque en los ejemplos de este patrón sí. npm Los módulos que componen la biblioteca AWS Construct se distribuyen a través del npm repositorio npmjs.org.

• AWS CloudFormationle ayuda a configurar AWS los recursos, aprovisionarlos de forma rápida y coherente y gestionarlos a lo largo de su ciclo de vida en todo el mundo. Cuentas de AWS Regiones de AWS

• AWS Lambda es un servicio de computación que ayuda a ejecutar código sin necesidad de aprovisionar ni administrar servidores. Ejecuta el código solo cuando es necesario y amplía la capacidad de manera automática, por lo que solo pagará por el tiempo de procesamiento que utilice.

• Amazon Route 53 es un servicio web de sistema de nombres de dominio (DNS) escalable y de alta disponibilidad.

• AWS WAFes un firewall de aplicaciones web que le ayuda a supervisar las solicitudes HTTP y HTTPS que se reenvían a los recursos de sus aplicaciones web protegidas.

Otras herramientas

• Bruno es un cliente de pruebas de API de código abierto y compatible con git.

• cdk-nag es una utilidad de código abierto que comprueba AWS CDK las mejores prácticas de las aplicaciones mediante paquetes de reglas.

Repositorio de código

El código de este patrón está disponible en el repositorio -api-gateway. GitHub path-based-versioning-with

Prácticas recomendadas

• Utilice una sólida canalización de integración y entrega continuas (CI/CD) para automatizar las pruebas y el despliegue de las CloudFormation pilas creadas con. AWS CDK Para obtener más información relacionada con esta recomendación, consulte la Guía de AWS DevOps Well-Architected.

• AWS WAF es un firewall gestionado que se integra fácilmente con servicios como Amazon API Gateway. Si bien AWS WAF no es un componente necesario para que este patrón de control de versiones funcione, recomendamos incluirlo en API Gateway como práctica recomendada AWS WAF de seguridad.

• Anima a los usuarios de API a que se actualicen periódicamente a la última versión de tu API para que las versiones anteriores queden obsoletas y se eliminen de forma eficiente.

• Antes de utilizar este enfoque en un entorno de producción, implementa una estrategia de firewall y autorización para tu API.

• Implemente el acceso a la gestión de sus AWS recursos Cuenta de AWS mediante el modelo de acceso con menos privilegios.

• Para aplicar las mejores prácticas y las recomendaciones de seguridad para las aplicaciones creadas con él AWS CDK, le recomendamos que utilice la utilidad cdk-nag.

Epics

Prepare su entorno local

Tarea	Descripción	Habilidades requeridas
Clonar el repositorio.	Para clonar el repositorio de aplicaciones de muestra, ejecute el siguiente comando: git clone https://github.com/aws-samples/path-based-versioning-with-api-gateway	Desarrollador de aplicaciones
Navegue hasta el repositorio clonado.	Para ir a la ubicación de la carpeta del repositorio clonado, ejecute el siguiente comando: cd api-gateway-custom-domain-versioning	Desarrollador de aplicaciones
Instale las dependencias requeridas.	Para instalar las dependencias necesarias, ejecute el siguiente comando: npm install	Desarrollador de aplicaciones

Prepare su entorno local

Tarea	Descripción	Habilidades requeridas
Clonar el repositorio.	Para clonar el repositorio de aplicaciones de muestra, ejecute el siguiente comando: git clone https://github.com/aws-samples/path-based-versioning-with-api-gateway	Desarrollador de aplicaciones
Navegue hasta el repositorio clonado.	Para ir a la ubicación de la carpeta del repositorio clonado, ejecute el siguiente comando: cd api-gateway-custom-domain-versioning	Desarrollador de aplicaciones
Instale las dependencias requeridas.	Para instalar las dependencias necesarias, ejecute el siguiente comando: npm install	Desarrollador de aplicaciones

Implemente la pila de CloudFormation enrutamiento

Tarea	Descripción	Habilidades requeridas
Inicie el despliegue de la pila de enrutamiento.	Para iniciar el despliegue de la pila de CloudFormation enrutamientoCustomDomainRouterStack, ejecute el siguiente comando y example.com sustitúyalo por el nombre del dominio del que es propietario: npx cdk deploy CustomDomainRouterStack --parameters PrerequisiteDomainName=example.com nota La implementación de la pila no se realizará correctamente hasta que la siguiente tarea de validación del DNS del dominio se realice correctamente.	Desarrollador de aplicaciones

Implemente la pila de CloudFormation enrutamiento

Tarea	Descripción	Habilidades requeridas
Inicie el despliegue de la pila de enrutamiento.	Para iniciar el despliegue de la pila de CloudFormation enrutamientoCustomDomainRouterStack, ejecute el siguiente comando y example.com sustitúyalo por el nombre del dominio del que es propietario: npx cdk deploy CustomDomainRouterStack --parameters PrerequisiteDomainName=example.com nota La implementación de la pila no se realizará correctamente hasta que la siguiente tarea de validación del DNS del dominio se realice correctamente.	Desarrollador de aplicaciones

Verificar la propiedad del dominio

Tarea	Descripción	Habilidades requeridas
Verifica la propiedad de tu dominio.	El certificado permanecerá en estado de pendiente de validación hasta que demuestres la propiedad del dominio asociado. Para demostrar la propiedad, agrega registros CNAME a la zona alojada que está asociada al dominio. Para obtener más información, consulta la validación de DNS en la AWS Certificate Manager documentación. Agregar los registros adecuados permite que la CustomDomainRouterStack implementación se realice correctamente.	Desarrollador de aplicaciones, administrador de sistemas de AWS, administrador de redes
Crea un registro de alias que apunte a tu dominio personalizado de API Gateway.	Una vez que el certificado se haya emitido y validado correctamente, cree un registro de DNS que apunte a la URL de dominio personalizada de Amazon API Gateway. La URL del dominio personalizado se genera exclusivamente mediante el aprovisionamiento del dominio personalizado y se especifica como parámetro de CloudFormation salida. A continuación se muestra un ejemplo del registro: Política de enrutamiento: enrutamiento simple Nombre del registro: demo.api-gateway-custom-domain-versioning.example.com Alias: sí Tipo de registro: registro DNS de tipo «A» que apunta a un AWS recurso Valor: d-xxxxxxxxxx.execute-api.xx-xxxx-x.amazonaws.com TTL (segundos): 300	Desarrollador de aplicaciones, administrador de sistemas de AWS, administrador de redes

Verificar la propiedad del dominio

Tarea	Descripción	Habilidades requeridas
Verifica la propiedad de tu dominio.	El certificado permanecerá en estado de pendiente de validación hasta que demuestres la propiedad del dominio asociado. Para demostrar la propiedad, agrega registros CNAME a la zona alojada que está asociada al dominio. Para obtener más información, consulta la validación de DNS en la AWS Certificate Manager documentación. Agregar los registros adecuados permite que la CustomDomainRouterStack implementación se realice correctamente.	Desarrollador de aplicaciones, administrador de sistemas de AWS, administrador de redes
Crea un registro de alias que apunte a tu dominio personalizado de API Gateway.	Una vez que el certificado se haya emitido y validado correctamente, cree un registro de DNS que apunte a la URL de dominio personalizada de Amazon API Gateway. La URL del dominio personalizado se genera exclusivamente mediante el aprovisionamiento del dominio personalizado y se especifica como parámetro de CloudFormation salida. A continuación se muestra un ejemplo del registro: Política de enrutamiento: enrutamiento simple Nombre del registro: demo.api-gateway-custom-domain-versioning.example.com Alias: sí Tipo de registro: registro DNS de tipo «A» que apunta a un AWS recurso Valor: d-xxxxxxxxxx.execute-api.xx-xxxx-x.amazonaws.com TTL (segundos): 300	Desarrollador de aplicaciones, administrador de sistemas de AWS, administrador de redes

Implemente CloudFormation pilas e invoque la API

Tarea	Descripción	Habilidades requeridas
Implemente la pila de ApiStackV1.	Para implementar la ApiStackV1 pila, usa el siguiente comando: npm run deploy-v1 El siguiente código de CDK agrega el mapeo de API: var apiMapping = new CfnApiMapping(this, "ApiMapping", { apiId: this.lambdaRestApi.restApiId, domainName: props.customDomainName.domainName, stage: "api", apiMappingKey: "api/v1", });	Desarrollador de aplicaciones
Implemente la pila de ApiStackV2.	Para implementar la ApiStackV2 pila, usa el siguiente comando: npm run deploy-v2	Desarrollador de aplicaciones
Invoque la API .	Para invocar la API y probar los puntos finales de la API mediante Bruno, consulta las instrucciones de la sección Información adicional.	Desarrollador de aplicaciones

Implemente CloudFormation pilas e invoque la API

Tarea	Descripción	Habilidades requeridas
Implemente la pila de ApiStackV1.	Para implementar la ApiStackV1 pila, usa el siguiente comando: npm run deploy-v1 El siguiente código de CDK agrega el mapeo de API: var apiMapping = new CfnApiMapping(this, "ApiMapping", { apiId: this.lambdaRestApi.restApiId, domainName: props.customDomainName.domainName, stage: "api", apiMappingKey: "api/v1", });	Desarrollador de aplicaciones
Implemente la pila de ApiStackV2.	Para implementar la ApiStackV2 pila, usa el siguiente comando: npm run deploy-v2	Desarrollador de aplicaciones
Invoque la API .	Para invocar la API y probar los puntos finales de la API mediante Bruno, consulta las instrucciones de la sección Información adicional.	Desarrollador de aplicaciones

Eliminar recursos

Tarea	Descripción	Habilidades requeridas
Eliminación de recursos.	Para destruir los recursos asociados a esta aplicación de ejemplo, usa el siguiente comando: npx cdk destroy --all nota Asegúrese de limpiar todos los registros DNS de Route 53 que se hayan agregado manualmente para el proceso de verificación de la propiedad del dominio.	Desarrollador de aplicaciones

Eliminar recursos

Tarea	Descripción	Habilidades requeridas
Eliminación de recursos.	Para destruir los recursos asociados a esta aplicación de ejemplo, usa el siguiente comando: npx cdk destroy --all nota Asegúrese de limpiar todos los registros DNS de Route 53 que se hayan agregado manualmente para el proceso de verificación de la propiedad del dominio.	Desarrollador de aplicaciones

Solución de problemas

Problema

Solución

El CustomDomainRouterStack tiempo de espera para el despliegue se debe a que el certificado no se puede validar.

Asegúrese de haber agregado los registros CNAME de validación de DNS adecuados, tal como se describió en la tarea anterior. Es posible que el nuevo certificado siga mostrando el estado de Validación pendiente durante un máximo de 30 minutos después de agregar los registros de validación de DNS. Para obtener más información, consulte la validación de DNS en la AWS Certificate Manager documentación.

Recursos relacionados

• Implementación del control de versiones de API Gateway basado en encabezados con Amazon CloudFront: esta entrada del blog de AWS Compute ofrece una estrategia de control de versiones basada en encabezados como alternativa a la estrategia de control de versiones basada en rutas que se describe en este patrón.

• AWS CDK Taller: este taller introductorio se centra en la creación e implementación de aplicaciones mediante el uso de. AWS AWS Cloud Development Kit (AWS CDK) Este taller es compatible con Go, Python y TypeScript.

Información adicional

Probando tu API con Bruno

Le recomendamos que utilice Bruno, una herramienta de prueba de API de código abierto, para comprobar que el enrutamiento basado en rutas funciona correctamente en la aplicación de ejemplo. Este patrón proporciona una colección de muestras para facilitar las pruebas de la API de muestra.

Para invocar y probar tu API, sigue estos pasos:

1. Instala Bruno.

2. Abre Bruno.

3. En el repositorio de códigos de este patrón, selecciona Bruno/Sample-API- Gateway-Custom-Domain-Versioning y abre la colección.

4. Para ver el menú desplegable Entornos en la parte superior derecha de la interfaz de usuario (UI), selecciona cualquier solicitud de la colección.

5. En el menú desplegable Entornos, selecciona Configurar.

6. Sustituya el REPLACE_ME_WITH_YOUR_DOMAIN valor por su dominio personalizado.

7. Selecciona Guardar y, a continuación, cierra la sección de configuración.

8. Para el entorno Sandbox, compruebe que esté seleccionada la opción Activa.

9. Para invocar la API, utilice el botón -> de la solicitud seleccionada.

10. Observa cómo se gestiona la validación (pasando valores distintos de números) en la V1 en comparación con la V2.

Para ver capturas de pantalla de ejemplos de invocación a una API y una comparación de las validaciones de la V1 y la V2, consulta Probar una API de muestra en el README.md archivo del repositorio de códigos de este patrón.