Configurar una solicitud de método en API Gateway - Amazon API Gateway
Configurar recursos de APIConfigurar un método HTTPConfigurar parámetros de solicitud de métodoConfiguración de un modelo de solicitud de métodoConfigurar la autorización de solicitud de métodoConfigurar la validación de solicitud de método

Configurar una solicitud de método en API Gateway

Configurar una solicitud de método implica realizar las siguientes tareas, después de la creación de un recurso RestApi:

  1. Creación de una nueva API o elección de una entidad Resource de API existente.

  2. Creación de un recurso Method de API que sea un verbo HTTP específico en el Resource nuevo o elegido de la API. Esta tarea se puede dividir aún más en las siguientes subtareas:

    • Añadido de un método HTTP a la solicitud de métodos

    • Configuración de parámetros de solicitudes

    • Definición de un modelo para el cuerpo de la solicitud

    • Aplicación de un esquema de autorización

    • Habilitación de la validación de la solicitud

Puede realizar estas tareas con los siguientes métodos:

Configurar recursos de API

En una API de API Gateway, los recursos que se pueden dirigir se exponen como un árbol de entidades Resources de API, con el recurso de raíz (/) en la parte superior de la jerarquía. El recurso de raíz depende de la URL base de la API, que se compone del punto de enlace de la API y un nombre de etapa. En la consola de API Gateway, este URI base se denomina Invoke URI y se muestra en el editor de etapas de la API una vez que se implementa la API.

El punto de enlace de la API puede ser un nombre de host predeterminado o un nombre de dominio personalizado. El nombre de host predeterminado tiene el siguiente formato:

{api-id}.execute-api.{region}.amazonaws.com

En este formato, la {api-id} representa el identificador de la API que genera API Gateway. La variable {region} representa la región de AWS (por ejemplo, us-east-1) que eligió al crear la API. Un nombre de dominio personalizado es cualquier nombre fácil de recordar en un dominio de Internet válido. Por ejemplo, si ha registrado un dominio de Internet de example.com, *.example.com es un nombre de dominio personalizado válido. Para obtener más información, consulte configurar nombres de dominio personalizados.

Para la API de ejemplo de PetStore, el recurso de raíz (/) expone la tienda de mascotas. El recurso /pets representa la variedad de mascotas disponibles en la tienda. El /pets/{petId} expone una mascota individual de un identificador concreto (petId). El parámetro de la ruta de {petId} forma parte de los parámetros de solicitudes.

Para configurar un recurso de API, se elige un recurso existente como principal y, a continuación, se crea el recurso secundario bajo el recurso principal. Se empieza con el recurso raíz como principal, se añade un recurso a este principal, se añade otro recurso a este recurso secundario como nuevo principal, etc., a su identificador principal. A continuación, se añade el recurso designado al principal.

Con la AWS CLI, puede llamar al comando get-resources para averiguar qué recursos de una API están disponibles:

aws apigateway get-resources --rest-api-id <apiId> \
                             --region <region>

El resultado es una lista de los recursos disponibles de la API actualmente. En la API de nuestro ejemplo de PetStore, esta lista sería similar a la siguiente:

{
    "items": [
        {
            "path": "/pets", 
            "resourceMethods": {
                "GET": {}
            }, 
            "id": "6sxz2j", 
            "pathPart": "pets", 
            "parentId": "svzr2028x8"
        }, 
        {
            "path": "/pets/{petId}", 
            "resourceMethods": {
                "GET": {}
            }, 
            "id": "rjkmth", 
            "pathPart": "{petId}", 
            "parentId": "6sxz2j"
        }, 
        {
            "path": "/", 
            "id": "svzr2028x8"
        }
    ]
}

Cada elemento enumera los identificadores del recurso (id) y, excepto el recurso raíz, su recurso principal inmediato (parentId), así como el nombre del recurso (pathPart). El recurso raíz es especial, ya que no tiene ninguno principal. Después de elegir un recurso como principal, llame al siguiente comando para añadir un recurso secundario. 

aws apigateway create-resource --rest-api-id <apiId> \
                             --region <region> \
                             --parent-id <parentId> \
                             --path-part <resourceName>

Por ejemplo, para añadir alimentos de mascotas para la venta en el sitio web de PetStore, añada un recurso food a la raíz (/), estableciendo path-part para food y parent-id para svzr2028x8. El resultado es similar al siguiente:

{
    "path": "/food", 
    "pathPart": "food", 
    "id": "xdsvhp", 
    "parentId": "svzr2028x8"
}

Utilizar un recurso proxy para simplificar la configuración de API

A medida que crece el negocio, el propietario de PetStore puede que decida añadir a la venta alimentos, juguetes y otros artículos relacionados con mascotas. Para sustentarlo, puede añadir /food, /toys y otros recursos debajo del recurso raíz. Debajo de cada categoría de venta, es posible que también desee añadir más recursos, como por ejemplo /food/{type}/{item}, /toys/{type}/{item}, etc. Esto puede ser una tarea tediosa. Si decide añadir una capa intermedia {subtype} a las rutas de recursos para cambiar la jerarquía de rutas a /food/{type}/{subtype}/{item}, /toys/{type}/{subtype}/{item}, etc., los cambios afectarán a la configuración existente de la API. Para evitarlo, puede utilizar un recurso de proxy de API Gateway para exponer un conjunto de recursos de la API a la vez.

API Gateway define un recurso de proxy como un marcador de posición para que un recurso se especifique cuando se envíe la solicitud. Un recurso de proxy se expresa mediante un parámetro de ruta especial de {proxy+}, a menudo denominado parámetro de ruta expansiva. El signo + indica los recursos secundarios que lleva asociados. El marcador de posición /parent/{proxy+} equivale a cualquier recurso que coincida con el patrón de ruta de /parent/*. El nombre de parámetro de ruta expansiva, proxy, se puede sustituir con otra cadena, del mismo modo que se trata un nombre de parámetro de ruta normal.

Con la AWS CLI, llama al siguiente comando para configurar un recurso de proxy bajo la raíz (/{proxy+}):

aws apigateway create-resource --rest-api-id <apiId> \
                             --region <region> \
                             --parent-id <rootResourceId> \
                             --path-part {proxy+}

El resultado es similar al siguiente:

{
    "path": "/{proxy+}", 
    "pathPart": "{proxy+}", 
    "id": "234jdr", 
    "parentId": "svzr2028x8"
}

Para el ejemplo de API de PetStore, puede utilizar /{proxy+} para representar tanto /pets como /pets/{petId}. Este recurso de proxy también puede hacer referencia a cualquier otro recurso (existente o que se vaya a añadir), como por ejemplo /food/{type}/{item}, /toys/{type}/{item}, etc., o /food/{type}/{subtype}/{item}, /toys/{type}/{subtype}/{item}, etc. El desarrollador del backend determina la jerarquía de recursos y el desarrollador cliente es responsable de comprenderlo. API Gateway simplemente transfiere lo que envíe el cliente al backend.

Una API puede tener más de un recurso de proxy. Por ejemplo, los siguientes recursos de proxy están permitidos dentro de una API, lo que supone que /parent/{proxy+} no está en el mismo segmento principal que /parent/{child}/{proxy+}.

/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}

Cuando un recurso de proxy tiene elementos secundarios que no son de proxy, los recursos secundarios se excluyen de la representación del recurso de proxy. En los ejemplos anteriores, /{proxy+} hace referencia a cualquier recurso bajo el recurso raíz, excepto los recursos /parent[/*]. En otras palabras, una solicitud de método realizada para un recurso específico prevalece sobre una solicitud de método realizada para un recurso genérico en el mismo nivel de la jerarquía de recursos.

Un recurso de proxy no puede tener cualquier recurso secundario. Un recurso de API después de {proxy+} es redundante y ambiguo. Los siguientes recursos de proxy no se permiten dentro de una API.

/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}

Configurar un método HTTP

Una solicitud de métodos de API se encapsula mediante el recurso Method de API Gateway. Para configurar la solicitud de método, primero debe iniciar el recurso Method, configurando al menos un método HTTP y un tipo de autorización en el método.

API Gateway, estrechamente asociado con el recurso de proxy, admite un método HTTP de ANY. Este método ANY representa cualquier método HTTP que se suministre en el tiempo de ejecución. Le permite utilizar una sola configuración de método de API para todos los métodos HTTP admitidos de DELETE, GET, HEAD, OPTIONS, PATCH, POST y PUT.

También puede configurar el método ANY en un recurso que no sea de proxy. Al combinar el método ANY con un recurso de proxy, obtiene una configuración de método de API único para todos los métodos compatibles con HTTP frente a cualquier recurso de una API. Además, el backend puede evolucionar sin que afecte a la configuración de API existente.

Antes de configurar un método de API, tenga en cuenta quién puede llamar al método. Establezca el tipo de autorización según su plan. Para un acceso abierto, establézcalo en NONE. Para utilizar permisos de IAM, establezca el tipo de autorización en AWS_IAM. Para utilizar una función de autorizador de Lambda, establezca esta propiedad en CUSTOM. Para utilizar un grupo de usuarios de Amazon Cognito, establezca el tipo de autorización en COGNITO_USER_POOLS.

El siguiente comando de la AWS CLI muestra cómo crear una solicitud de método del verbo ANY frente a un recurso especificado (6sxz2j), mediante los permisos de IAM para controlar su acceso. 

aws apigateway put-method --rest-api-id vaz7da96z6 \
       --resource-id 6sxz2j \
       --http-method ANY \
       --authorization-type AWS_IAM \
       --region us-west-2

Para crear una solicitud de método de API con un tipo de autorización distinta, consulte Configurar la autorización de solicitud de método.

Configurar parámetros de solicitud de método

Los parámetros de solicitud de método son una forma para que un cliente proporcione los datos de entrada o el contexto de ejecución necesarios para completar la solicitud de métodos. Un parámetro de método puede ser un método de ruta, un encabezado o un parámetro de cadena de consulta. Como parte de la configuración de solicitud de método, debe declarar los parámetros de solicitud necesarios para que estén disponibles para el cliente. Para la integración que no sea de proxy, puede traducir estos parámetros de solicitud en un formato que sea compatible con el requisito del backend.

Por ejemplo, para la solicitud de métodos GET /pets/{petId}, la variable de ruta {petId} es un parámetro de solicitud necesario. Puede declarar este parámetro de ruta cuando llame al comando put-method de la AWS CLI. Esto se detalla de la siguiente manera:

aws apigateway put-method --rest-api-id vaz7da96z6 \
       --resource-id rjkmth \
       --http-method GET \
       --authorization-type "NONE" \
       --region us-west-2 \
       --request-parameters method.request.path.petId=true

Si un parámetro no es necesario, puede establecerlo en false en request-parameters. Por ejemplo, si el método GET /pets utiliza un parámetro de cadena de consulta opcional de type y un parámetro de encabezado opcional de breed, puede declararlos usando el siguiente comando de la CLI, suponiendo que el recurso /pets sea id 6sxz2j:

aws apigateway put-method --rest-api-id vaz7da96z6 \
       --resource-id 6sxz2j \
       --http-method GET \
       --authorization-type "NONE" \
       --region us-west-2 \
       --request-parameters method.request.querystring.type=false,method.request.header.breed=false

En lugar de esta forma abreviada, puede utilizar una cadena de JSON para establecer el valor request-parameters:

'{"method.request.querystring.type":false,"method.request.header.breed":false}'

Con esta configuración, el cliente puede consultar las mascotas por tipo: 

GET /pets?type=dog

Además, el cliente puede consultar los perros de raza caniche de la siguiente manera:

GET /pets?type=dog
breed:poodle

Para obtener información sobre cómo asignar parámetros de solicitud de método a parámetros de solicitud de integración, consulte Integraciones para las API de REST en API Gateway.

Configuración de un modelo de solicitud de método

Para un método de API que pueda tomar datos de entrada en una carga, puede utilizar un modelo. Un modelo se expresa en un esquema JSON, borrador 4 y describe la estructura de datos del cuerpo de la solicitud. Con un modelo, un cliente puede determinar cómo construir una carga de solicitud de métodos como entrada. Y lo que es más importante, API Gateway utiliza el modelo para validar una solicitud, generar un SDK e inicializar una plantilla de mapeo para configurar la integración en la consola de API Gateway. Para obtener información sobre cómo crear un modelo, consulte Comprensión de los modelos de datos.

En función de los tipos de contenido, una carga de método puede tener diferentes formatos. Un modelo se indexa frente al tipo de medio de la carga aplicada. API Gateway utiliza el encabezado de la solicitud Content-Type para determinar el tipo de contenido. Para configurar modelos de solicitud de método, añada pares de clave-valor con el formato "<media-type>":"<model-name>" al mapa requestModels cuando llame al comando put-method de la AWS CLI.

Para utilizar el mismo modelo independientemente del tipo de contenido, especifique $default como la clave.

Por ejemplo, para establecer un modelo en la carga de JSON de la solicitud de método POST /pets de la API de ejemplo de PetStore, puede llamar al siguiente comando de la AWS CLI:

aws apigateway put-method \
       --rest-api-id vaz7da96z6 \
       --resource-id 6sxz2j \
       --http-method POST \
       --authorization-type "NONE" \
       --region us-west-2 \
       --request-models '{"application/json":"petModel"}'

Aquí, petModel es el valor de propiedad name de un recurso Model que describe una mascota. La definición del esquema real se expresa como un valor de cadena JSON de la propiedad schema del recurso Model.

En un SDK Java de la API, u otro tipo de SDK con establecimiento inflexible de tipos, los datos de entrada se forman como la clase petModel derivada de la definición del esquema. Con el modelo de solicitud, los datos de entrada en el SDK generado se forman en la clase Empty, que se deriva del modelo Empty predeterminado. En este caso, el cliente no puede crear una instancia de la clase de datos correcta para proporcionar la entrada necesaria.

Configurar la autorización de solicitud de método

Para controlar quién puede llamar al método de la API, puede configurar el tipo de autorización en el método. Puede utilizar este tipo para aplicar uno de los autorizadores admitidos, incluidos roles y políticas de IAM (AWS_IAM), un grupo de usuarios de Amazon Cognito (COGNITO_USER_POOLS), o un autorizador de Lambda basado en funciones de Lambda (CUSTOM).

Para utilizar permisos de IAM para autorizar el acceso al método de la API, establezca la propiedad de entrada authorization-type en AWS_IAM. Cuando esta opción está establecida, API Gateway verifica la firma del intermediario en la solicitud en función de las credenciales del intermediario. Si el usuario verificado tiene permiso para llamar al método, se acepta la solicitud. De lo contrario, rechaza la solicitud y el intermediario recibe una respuesta de error no autorizado. La llamada al método no se realiza correctamente a menos que el intermediario tenga permiso para invocar el método de la API. La siguiente política de IAM concede permiso al intermediario para llamar a cualquier método de API creado dentro de la misma Cuenta de AWS: 

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": "arn:aws:execute-api:*:*:*"
        }
    ]
}

Para obtener más información, consulte Control del acceso a una API de REST con permisos de IAM.

Actualmente, solo puedes conceder esta política a los usuarios, grupos y roles de la Cuenta de AWS del propietario de la API. Los usuarios de una Cuenta de AWS diferente pueden llamar a los métodos de la API solo si se les permite asumir un rol de la Cuenta de AWS del propietario de la API con los permisos necesarios para llamar a la acción execute-api:Invoke. Para obtener más información sobre los permisos entre cuentas, consulte Uso de roles de IAM.

Puede utilizar la AWS CLI, un AWS SDK o un cliente de API de REST, como Postman, que implementa la firma de Signature Version 4 (SigV4).

Para utilizar un autorizador de Lambda con el fin de autorizar el acceso al método de la API, establezca la propiedad de entrada authorization-type en CUSTOM y establezca la propiedad de entrada authorizer-id en el valor de propiedad id de un autorizador de Lambda que ya exista. El autorizador de Lambda al que se hace referencia puede ser del tipo TOKEN o REQUEST. Para obtener información acerca de cómo crear un autorizador de Lambda, consulte Uso de autorizadores Lambda de API Gateway.

Para utilizar un grupo de usuarios de Amazon Cognito con el fin de autorizar el acceso al método de la API, establezca la propiedad de entrada authorization-type en COGNITO_USER_POOLS y establezca la propiedad de entrada authorizer-id en el valor de propiedad id del autorizador COGNITO_USER_POOLS que ya se creó. Para obtener información sobre la creación de un autorizador de grupo de usuarios de Amazon Cognito, consulte Control del acceso a las API de REST con grupos de usuarios de Amazon Cognito como autorizador.

Configurar la validación de solicitud de método

Puede habilitar la validación de solicitud al configurar una solicitud de método de API. Primero tiene que crear un validador de solicitudes:

aws apigateway create-request-validator \
    --rest-api-id 7zw9uyk9kl \
    --name bodyOnlyValidator \
    --validate-request-body  \
    --no-validate-request-parameters

Este comando de la CLI crea un validador de solicitud de solo cuerpo. A continuación, se muestra un ejemplo de resultado:

{
    "validateRequestParameters": false, 
    "validateRequestBody": true, 
    "id": "jgpyy6", 
    "name": "bodyOnlyValidator"
}

Con este validador de solicitud, puede habilitar la validación de solicitud como parte de la configuración de solicitud de método: 

aws apigateway put-method \
    --rest-api-id 7zw9uyk9kl 
    --region us-west-2 
    --resource-id xdsvhp 
    --http-method PUT 
    --authorization-type "NONE" 
    --request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' 
    --request-models '{"application/json":"petModel"}'
    --request-validator-id jgpyy6

Para que se incluya en la validación de solicitud, debe declararse un parámetro de solicitud como sea necesario. Si el parámetro de cadena de consulta de la página se utiliza en la validación de solicitud, el mapa de request-parameters del ejemplo anterior debe especificarse como '{"method.request.querystring.type": false, "method.request.querystring.page":true}'.