Trabajar con mapeos de la API para las API REST

Los mapeos de la API se utilizan para conectar etapas de la API a un nombre de dominio personalizado. Después de crear un nombre de dominio y configurar registros DNS, se utilizan mapeos de la API para enviar tráfico a las API a través del nombre de dominio personalizado.

Un mapeo de la API especifica una API, una etapa y, de forma opcional, una ruta que se utilizará para el mapeo. Por ejemplo, puede mapear la etapa de production de una API a https://api.example.com/orders.

Puede mapear etapas de la API HTTP y REST al mismo nombre de dominio personalizado.

Antes de crear un mapeo de la API, debe tener una API, una etapa y un nombre de dominio personalizado. Para obtener más información sobre cómo crear un nombre de dominio personalizado, consulte Configuración de un nombre de dominio regional personalizado en API Gateway.

Enrutamiento de solicitudes de la API

Puede configurar mapeos de la API con varios niveles, por ejemplo orders/v1/items y orders/v2/items.

nota

Para configurar mapeos de la API con varios niveles, el nombre de dominio personalizado debe ser regional y utilizar la política de seguridad de TLS 1.2.

Para mapeos de la API con varios niveles, API Gateway enruta las solicitudes al mapeo de la API que tiene la ruta coincidente más larga. API Gateway solo considera las rutas configuradas para los mapeos de la API, y no las rutas de la API, para seleccionar la API que se va a invocar. Si ninguna ruta coincide con la solicitud, API Gateway envía la solicitud a la API que ha mapeado a la ruta vacía (none).

En el caso de los nombres de dominio personalizados que utilizan mapeos de la API con varios niveles, API Gateway enruta las solicitudes al mapeo de la API que tiene el prefijo coincidente más largo.

Por ejemplo, considere un nombre de dominio personalizado https://api.example.com con los siguientes mapeos de la API:

1. (none) mapeado a la API 1.

2. orders mapeado a la API 2.

3. orders/v1/items mapeado a la API 3.

4. orders/v2/items mapeado a la API 4.

5. orders/v2/items/categories mapeado a la API 5.

Solicitud	API seleccionada	Explicación
https://api.example.com/orders	API 2	La solicitud coincide exactamente con este mapeo de la API.
https://api.example.com/orders/v1/items	API 3	La solicitud coincide exactamente con este mapeo de la API.
https://api.example.com/orders/v2/items	API 4	La solicitud coincide exactamente con este mapeo de la API.
https://api.example.com/orders/v1/items/123	API 3	API Gateway elige el mapeo que tiene la ruta de coincidencia más larga. El 123 al final de la solicitud no afecta a la selección.
https://api.example.com/orders/v2/items/categories/5	API 5	API Gateway elige el mapeo que tiene la ruta de coincidencia más larga.
https://api.example.com/customers	API 1	API Gateway utiliza la asignación vacía como un catch-all.
https://api.example.com/ordersandmore	API 2	API Gateway elige el mapeo que tiene el prefijo de coincidencia más largo. Para un nombre de dominio personalizado configurado con mapeos de un solo nivel, por ejemplo, solo https://api.example.com/orders y https://api.example.com/, API Gateway elegiría API 1, ya que no hay una ruta que coincida con ordersandmore.

Restricciones

• En un mapeo de la API, el nombre de dominio personalizado y las API mapeadas deben estar en la misma cuenta de AWS.

• Los mapeos de la 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 mapear las API HTTP a un nombre de dominio regional personalizado con la política de seguridad de TLS 1.2.

• No puede mapear las API de WebSocket al mismo nombre de dominio personalizado que una API HTTP o API REST.

Creación de un mapeo de la API

Para crear un mapeo de la API, primero debe crear un nombre de dominio personalizado, una API y una etapa. Para obtener información sobre cómo crear un nombre de dominio personalizado, consulte Configuración de un nombre de dominio regional personalizado en API Gateway.

Para ver ejemplos de las plantillas de AWS Serverless Application Model que crean todos los recursos, consulte Sessions With SAM en GitHub.

AWS Management Console

Para crear un mapeo de la API

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. Elija Custom domain names (Nombres de dominio personalizados).

3. Seleccione un nombre de dominio personalizado que ya haya creado.

4. Elija API mappings (Mapeos de la API).

5. Elija Configure API mappings (Configurar asignaciones de API).

6. Seleccione Add new mapping (Agregar nueva asignación).

7. Introduzca una API, una Stage (Etapa) y, de forma opcional, una Path (Ruta).

8. Seleccione Save.

AWS CLI

El siguiente comando de la AWS CLI crea un mapeo de la API. En este ejemplo, API Gateway envía solicitudes a api.example.com/v1/orders a la API y a la etapa especificada.

nota

Para crear mapeos de la API con varios niveles, debe utilizar apigatewayv2.

aws apigatewayv2 create-api-mapping \
    --domain-name api.example.com \
    --api-mapping-key v1/orders \
    --api-id a1b2c3d4 \
    --stage test

AWS CloudFormation

El siguiente ejemplo de AWS CloudFormation crea un mapeo de la API.

nota

Para crear mapeos de la API con varios niveles, debe utilizar AWS::ApiGatewayV2.

MyApiMapping:
  Type: 'AWS::ApiGatewayV2::ApiMapping'
  Properties:
    DomainName: api.example.com
    ApiMappingKey: 'orders/v2/items'
    ApiId: !Ref MyApi
    Stage: !Ref MyStage