Implementación del control de versiones de API basado en rutas mediante dominios personalizados en Amazon API Gateway

Corey Schnedl, Marcelo Barbosa, Mario Lopez Martinez, Anbazhagan Ponnuswamy, Gaurav Samudra y Abhilash Vinod, Amazon Web Services

Resumen

Este patrón demuestra cómo puede utilizar la característica de asignación de API de dominios personalizados para implementar una solución de control de versiones de API basado 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. Puede utilizar las asignaciones de API para conectar 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.

Cuando 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 características y funcionalidades. Sin embargo, no es aconsejable cambiar ni eliminar las características existentes. Cualquier cambio importante podría afectar a las aplicaciones del consumidor y provocar fallos durante el tiempo de ejecución. El control de versiones de las API es importante para evitar interrumpir la compatibilidad con versiones anteriores e infringir 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 más utilizado. 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

Limitaciones

Versiones de producto

Arquitectura

En el siguiente diagrama se muestra el flujo de trabajo de la arquitectura.

En el siguiente diagrama se ilustra lo siguiente:

Automatización y escala

Te recomendamos que utilices AWS CloudFormation pilas independientes para cada versión de la 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, puede mantener diferentes versiones de su API sin necesidad de duplicar el código fuente para las nuevas versiones. Con Gitflow, puede agregar etiquetas a las confirmaciones dentro de su repositorio de Git a medida que se vayan llevando a cabo los lanzamientos. Como resultado, tiene una instantánea completa del código fuente en relación con un lanzamiento específico. Como es necesario realizar actualizaciones, puedes consultar el código de una versión específica, realizar actualizaciones y, después, 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.

Tools (Herramientas)

Servicios de AWS

Otras herramientas

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

Epics

git clone https://github.com/aws-samples/path-based-versioning-with-api-gateway

cd api-gateway-custom-domain-versioning

npm install 

npx cdk deploy CustomDomainRouterStack --parameters PrerequisiteDomainName=example.com

npm run deploy-v1

var apiMapping = new CfnApiMapping(this, "ApiMapping", {
      apiId: this.lambdaRestApi.restApiId,
      domainName: props.customDomainName.domainName,
      stage: "api",
      apiMappingKey: "api/v1",
    });

npm run deploy-v2

npx cdk destroy --all

Resolución de problemas

Recursos relacionados

Información adicional

Prueba de la 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 ejemplo para facilitar las pruebas de la API de ejemplo.

Para invocar y probar la API, use los siguientes pasos:

Para ver capturas de pantalla de ejemplos de invocación de la API y una comparación de las validaciones de V1 y V2, consulte Testing your sample API en el archivo README.md del repositorio de código de este patrón.