# Uso de las asignaciones de API para conectar etapas de API a un nombre de dominio personalizado para las API de REST
<a name="rest-api-mappings"></a>

Las asignaciones de API se utilizan para conectar etapas de la API a un nombre de dominio personalizado. Esto envía el tráfico a sus API a través de su nombre de dominio personalizado.

Una asignación de API especifica una API, una etapa y, de forma opcional, una ruta que se utilizará para la asignación. Por ejemplo, puede asignar `https://api.example.com/orders` a la etapa `production` de una API.

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

Antes de crear una asignación de 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 personalizado regional en API Gateway](apigateway-regional-api-custom-domain-create.md).

## Solicitudes entrantes para el nombre de dominio personalizado
<a name="rest-api-mappings-incoming-requests"></a>

Cuando asigna un nombre de dominio personalizado a una etapa de la API, API Gateway elimina la ruta base entrante. Esto elimina la ruta base asignada de la invocación a la API. Por ejemplo, si la asignación de ruta base fuera `https://api.example.com/orders/shop/5` para la etapa `test` y utilizara la siguiente solicitud, `https://api.example.com/orders/shop/5/hats`, API Gateway invocaría el recurso `/hats` de la etapa `test` de la API, no el recurso `orders/shop/5/hats`.

## Asignación de solicitudes a la API
<a name="rest-api-mappings-evalutation"></a>

A continuación se explica cómo API Gateway evalúa las asignaciones de la API.

Puede crear una asignación de la API mediante asignaciones de un solo nivel, como una asignación de la API desde `orders` a la etapa `beta` de una API y una asignación de la API desde `shipping` a la etapa `alpha` de una API. En el caso de los nombres de dominio personalizados regionales con la política de seguridad TLS 1.2, API Gateway admite asignaciones de la API de varios niveles. Puede crear una asignación de la API de `orders/v1/items` a la etapa `alpha` de una API y de `orders/v2/items` a la etapa `beta` de una API. Cuando crea una asignación con varios niveles, API Gateway envía las solicitudes a la asignación de la API que tenga la ruta de coincidencia más larga.

Puede crear una asignación de la API a la ruta vacía `(none)`. Si ninguna ruta coincide con la solicitud, API Gateway envía la solicitud a la ruta vacía `(none)`.

En este ejemplo, el nombre de dominio personalizado `https://api.example.com` tiene las siguientes asignaciones de la API.


|  Asignación de API  |  API seleccionada  | 
| --- | --- | 
|  `(none)`  |   API 1   | 
|   `orders`   |   API 2   | 
|  `orders/v1/items`  |   API 3   | 
|  `orders/v2/items`  |   API 4   | 
|  `orders/v1/items/categories`  |   API 5   | 

En la siguiente tabla se muestra cómo API Gateway aplica las asignaciones de API anteriores a las solicitudes de ejemplo.


| Solicitud | API seleccionada | Explicación | 
| --- | --- | --- | 
|  `https://api.example.com/orders`  |  API 2  |  La solicitud coincide exactamente con esta asignación de API.  | 
|  `https://api.example.com/orders/v1/items`  |  API 3  |  La solicitud coincide exactamente con esta asignación de API.  | 
|  `https://api.example.com/orders/v2/items`  |  API 4  |  La solicitud coincide exactamente con esta asignación de API.  | 
|  `https://api.example.com/orders/v1/items/123`  |  API 3  |  API Gateway elige la asignación con la ruta de coincidencia más larga. El `123` al final de la solicitud no afecta a la selección. Consulte [Solicitudes entrantes para el nombre de dominio personalizado](#rest-api-mappings-incoming-requests).  | 
|  `https://api.example.com/orders/v2/items/categories/5`  |  API 5  |  API Gateway elige la asignación con 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 la asignación con el prefijo de coincidencia más largo. En el caso de un nombre de dominio personalizado configurado con asignaciones 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
<a name="rest-api-mappings-restrictions"></a>
+ En el caso de una asignación de API, el nombre de dominio personalizado y las API asignadas deben pertenecer a la misma cuenta de AWS.
+ Las asignaciones de API deben contener solo letras, números y los siguientes caracteres: `$-_.+!*'()/`.
+ La longitud máxima de la ruta en una asignación de API es de 300 caracteres.
+ Puede tener 200 asignaciones de API con varios niveles para cada nombre de dominio. Este límite no incluye la asignación de la API con niveles únicos, como `/prod`.
+ Solo puede asignar API HTTP a un nombre de dominio regional personalizado con la política de seguridad de TLS 1.2.
+ No puede asignar las API de WebSocket al mismo nombre de dominio personalizado que una API HTTP o API REST.
+ Después de crear sus asignaciones de API, debe crear o actualizar el registro de recursos del proveedor de DNS para asignarlo al punto de conexión de la API.
+ Si crea una asignación de API con varios niveles, API Gateway convierte todos los nombres de encabezado a minúsculas.

## Creación de una asignación de API
<a name="rest-api-mappings-examples"></a>

Para crear una asignación de API, primero debe crear un nombre de dominio personalizado, una API y una etapa. El nombre de dominio personalizado debe tener un modo de enrutamiento establecido en `ROUTING_RULE_THEN_API_MAPPING` o `API_MAPPING_ONLY`. Para obtener información sobre cómo establecer el modo de enrutamiento, consulte [Establecimiento del modo de enrutamiento para el nombre de dominio personalizado](set-routing-mode.md).

Para ver ejemplos de las plantillas de AWS Serverless Application Model que crean todos los recursos, consulte [Sessions With SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) en GitHub.

------
#### [ Consola de administración de AWS ]

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

1. Elija **Custom domain names (Nombres de dominios personalizados)** en el panel de navegación principal. 

1. Elija un nombre de dominio personalizado.

1. En la pestaña **Detalles de enrutamiento**, elija **Configurar los mapeos de la API**.

1. Especifique los valores de **API**, **Etapa** y **Ruta** para el mapeo.

1. Seleccione **Save**.

------
#### [ AWS CLI ]

El siguiente comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) permite crear una asignación de API. En este ejemplo, API Gateway envía solicitudes a `api.example.com/v1/orders` a la API y a la etapa especificadas.

**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
```

------
#### [ CloudFormation ]

El siguiente ejemplo de 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
```

------