# Métodos de API de REST en API Gateway En API Gateway, un método de API incluye una [solicitud de método](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) y una [respuesta de método](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). Se configura un método de API para definir lo que un cliente debería o debe hacer para enviar una solicitud de acceso al servicio en el backend y para definir las respuestas que recibe a cambio el cliente. Para la entrada, puede elegir los parámetros de solicitud de método, o bien una carga aplicable, para que el cliente proporcione los datos necesarios u opcionales en el tiempo de ejecución. Para la salida, se determina el código de estado de respuesta del método, los encabezados y el cuerpo aplicable como destinos a los que asignar los datos de respuesta del backend, antes de que se devuelvan al cliente. Para ayudar al desarrollador cliente a comprender los comportamientos y los formatos de entrada y salida de su API, puede [documentar la API](api-gateway-documenting-api.md) y [ofrecer mensajes de error adecuados](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) para [solicitudes no válidas](api-gateway-method-request-validation.md). Una solicitud de método de API es una solicitud HTTP. Para configurar la solicitud de método, debe configurar un método (o verbo) HTTP, la ruta a un [recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API, los encabezados y los parámetros de cadenas de consulta aplicables. También configura una carga cuando el método HTTP es `POST`, `PUT`o `PATCH`. Por ejemplo, para recuperar una mascota con la [API de muestra PetStore](api-gateway-create-api-from-example.md), define la solicitud de método de API de `GET /pets/{petId}`, donde `{petId}` es un parámetro de ruta que puede tomar un número en tiempo de ejecución. ``` GET /pets/1 Host: apigateway.us-east-1.amazonaws.com ... ``` Si el cliente especifica una ruta incorrecta, por ejemplo, `/pet/1` o `/pets/one` en lugar de `/pets/1`, se lanza una excepción. Una respuesta de método de API es una respuesta HTTP con un código de estado determinado. Para una integración que no sea de proxy, debe configurar respuestas de método para especificar los destinos necesarios u opcionales de las asignaciones. Estos transforman los encabezados o el cuerpo de respuesta de la integración en encabezados o en cuerpo de respuesta de método. El mapeo puede ser tan sencillo como una [transformación de identidad](https://en.wikipedia.org/wiki/Identity_transform) que pasa los encabezados o el cuerpo a través de la integración tal y como están. Por ejemplo, la siguiente respuesta de método `200` muestra un ejemplo de transferencia de una respuesta de integración correcta tal y como está. ``` 200 OK Content-Type: application/json ... { "id": "1", "type": "dog", "price": "$249.99" } ``` En principio, puede definir una respuesta de método correspondiente a una respuesta específica desde el backend. Normalmente, esto implica cualquier respuesta 2XX, 4XX y 5XX. Sin embargo, puede que no sea práctico, porque a menudo es posible que no sepa con antelación todas las respuestas que puede devolver un backend. En la práctica, puede designar una respuesta de método como predeterminada para gestionar las respuestas desconocidas o no asignadas desde el backend. Es una buena práctica designar la respuesta 500 como predeterminada. En cualquier caso, debe configurar al menos una respuesta de método para integraciones que no sean de proxy. De lo contrario, API Gateway devuelve una respuesta de error 500 al cliente incluso cuando la solicitud se completa correctamente en el backend. Para admitir un SDK con establecimiento inflexible de tipos para la API, como un SDK de Java, debe definir el modelo de datos de entrada para la solicitud de método y definir el modelo de datos de salida de la respuesta de método. ## Requisitos previos Antes de configurar un método de API, verifique lo siguiente: + El método debe estar disponible en API Gateway. Siga las instrucciones en [Tutorial: Creación de una API de REST con integración no de proxy HTTP](api-gateway-create-api-step-by-step.md). + Si desea que el método se comunique con una función de Lambda, debe haber creado ya el rol de invocación de Lambda y el rol de ejecución de Lambda en IAM. También debe haber creado la función de Lambda con la que el método se comunicará en AWS Lambda. Para crear los roles y funciones, utilice las instrucciones de [Creación de una función de Lambda para la integración de Lambda no de proxy](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda) de [Elección de un tutorial de integración de AWS Lambda](getting-started-with-lambda-integration.md). + Si desea que el método se comunique con una integración HTTP o de proxy HTTP, debe haber creado y tener acceso a la URL del punto de conexión HTTP con la que se comunicará el método. + Compruebe que API Gateway admite los certificados de los puntos de conexión HTTP y proxy de HTTP. Para obtener más información, consulte [Entidades de certificación compatibles con API Gateway para las integraciones HTTP y Proxy HTTP en API Gateway](api-gateway-supported-certificate-authorities-for-http-endpoints.md). **Topics** + [Requisitos previos](#method-setting-prerequisites) + [Configurar una solicitud de método en API Gateway](api-gateway-method-settings-method-request.md) + [Configuración de una respuesta de método en API Gateway](api-gateway-method-settings-method-response.md) + [Configuración de un método con la consola de API Gateway](how-to-set-up-method-using-console.md) # 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](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html): 1. Creación de una nueva API o elección de una entidad [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API existente. 1. Creación de un recurso [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 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: + [Consola de API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console) + Comandos de la AWS CLI ([create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) y [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html)) + Función del SDK de AWS (como, en Node.js, [createResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) y [putMethod](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property)) + API REST de API Gateway ([resource:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html) y [method:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)). **Topics** + [Configurar recursos de API](#setup-method-resources) + [Configurar un método HTTP](#setup-method-add-http-method) + [Configurar parámetros de solicitud de método](#setup-method-request-parameters) + [Configuración de un modelo de solicitud de método](#setup-method-request-model) + [Configurar la autorización de solicitud de método](#setup-method-request-authorization) + [Configurar la validación de solicitud de método](#setup-method-request-validation) ## Configurar recursos de API En una API de API Gateway, los recursos que se pueden dirigir se exponen como un árbol de entidades [Resources](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html) 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 conexión 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 conexión 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 *\$1api-id\$1* 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](how-to-custom-domains.md). Para la [API de ejemplo de PetStore](api-gateway-create-api-from-example.md), 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. El siguiente comando [get-resources](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) permite recuperar todos los recursos de una API: ``` aws apigateway get-resources --rest-api-id apiId ``` En la API del ejemplo de PetStore, el resultado sería similar al 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, use el siguiente comando para agregar un recurso secundario. ``` aws apigateway create-resource --rest-api-id apiId \ --parent-id parentId \ --path-part resourceName ``` Por ejemplo, para agregar comida para mascotas a la venta en el sitio web de PetStore, use el siguiente comando: ``` aws apigateway create-resource --rest-api-id a1b2c3 \ --parent-id svzr2028x8 \ --path-part food ``` El resultado será 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](api-gateway-set-up-simple-proxy.md) 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/*`. Puede usar cualquier cadena para el nombre del parámetro de ruta expansiva. El siguiente comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) permite crear un recurso de proxy bajo la raíz (`/{proxy+}`): ``` aws apigateway create-resource --rest-api-id apiId \ --parent-id rootResourceId \ --path-part {proxy+} ``` El resultado será 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. En la siguiente tabla se muestra cómo API Gateway enruta las solicitudes a los siguientes recursos para la etapa `prod` de una API. ``` ANY /{proxy+} GET /pets/{proxy+} GET /pets/dog ``` | Solicitud | Ruta seleccionada | Explicación | | --- | --- | --- | | `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog` | `GET /pets/dog` | La solicitud coincide completamente con este recurso. | | `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats` | `GET /pets/{proxy+}` | La variable de ruta expansiva `/pets/{proxy+}` captura esta solicitud. | | `GET https://api-id.execute-api.region.amazonaws.com/prod/animals` | `GET /{proxy+}` | La variable de ruta expansiva `/{proxy+}` captura esta solicitud. | 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](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 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 [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) permite crear una solicitud de método para el verbo `ANY` utilizando permisos de IAM para controlar el acceso. ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method ANY \ --authorization-type AWS_IAM ``` 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](#setup-method-request-authorization). ## 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. El siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) permite crear un método con un parámetro de ruta obligatorio: ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id rjkmth \ --http-method GET \ --authorization-type "NONE" \ --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 `age`, puede declararlos usando el siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html): ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --authorization-type "NONE" \ --request-parameters method.request.querystring.type=false,method.request.header.age=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.age":false}' ``` Con esta configuración, el cliente puede consultar las mascotas por tipo: ``` GET /pets?type=dog ``` Y el cliente puede consultar qué perros son cachorros de la siguiente manera: ``` GET /pets?type=dog age:puppy ``` 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](how-to-integration-settings.md). ## 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](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) 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](api-gateway-method-request-validation.md), [generar un SDK](how-to-generate-sdk.md) 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](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html), consulte [Comprensión de los modelos de datos](models-mappings-models.md). 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 AWS CLI de la `put-method`. Para utilizar el mismo modelo independientemente del tipo de contenido, especifique `$default` como la clave. Por ejemplo, para establecer un modelo en la carga útil de JSON de la solicitud del método `POST /pets` de la API de ejemplo de PetStore, puede usar el siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html): ``` aws apigateway put-method \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method POST \ --authorization-type "NONE" \ --request-models '{"application/json":"petModel"}' ``` Aquí, `petModel` es el valor de propiedad `name` de un recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) que describe una mascota. La definición del esquema real se expresa como un valor de cadena JSON de la propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#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](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType) 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\$1IAM**. 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: ------ #### [ JSON ] **** ``` { "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](permissions.md). 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). Puede utilizar la AWS CLI, un AWS SDK o un cliente de API de REST, como [Postman](https://www.postman.com/), que implementa la [firma de Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). 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 [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) en el valor de propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#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](apigateway-use-lambda-authorizer.md). 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 [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) en el valor de propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#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](apigateway-integrate-with-cognito.md). ## 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 debe crear un [validador de solicitudes](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html). El siguiente comando [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html) permite crear un validador de solicitud de solo cuerpo. ``` aws apigateway create-request-validator \ --rest-api-id 7zw9uyk9kl \ --name bodyOnlyValidator \ --validate-request-body \ --no-validate-request-parameters ``` El resultado será similar al siguiente: ``` { "validateRequestParameters": false, "validateRequestBody": true, "id": "jgpyy6", "name": "bodyOnlyValidator" } ``` Con este validador de solicitud, puede usar la validación de solicitudes como parte de la configuración de solicitudes del método. El siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) permite crear una solicitud de método que requiera que el cuerpo de la solicitud entrante coincida con el `PetModel` y tiene dos parámetros de solicitud que no son obligatorios: ``` aws apigateway put-method \ --rest-api-id 7zw9uyk9kl \ --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 incluir un parámetro de solicitud en la validación de la solicitud, debe establecer `validateRequestParameters` en `true` para el validador de solicitudes, y establecer el parámetro de solicitud específico en `true` en el comando `put-method`. # Configuración de una respuesta de método en API Gateway Una respuesta de método de API encapsula el resultado de una solicitud de método de API que el cliente recibirá. Los datos de salida incluyen un código de estado HTTP, algunos encabezados y posiblemente un cuerpo. Con las integraciones que no sean de proxy, los parámetros de respuesta especificados y el cuerpo se pueden asignar desde los datos de respuesta de integración asociados o se les pueden asignar determinados valores estáticos según las asignaciones. Estas asignaciones se especifican en la respuesta de integración. La asignación puede ser una transformación idéntica que transfiere la respuesta de integración tal y como es. Con una integración de proxy, API Gateway transfiere la respuesta del backend a la respuesta del método automáticamente. No es necesario configurar la respuesta del método de API. Sin embargo, con la integración proxy de Lambda, la función de Lambda debe devolver un resultado de [este formato de salida](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format) para que API Gateway asigne correctamente la respuesta de integración a una respuesta de método. Mediante programación, la configuración de la respuesta de método equivale a crear un recurso [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) de API Gateway y a establecer las propiedades de [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) y [responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels). Al establecer códigos de estado para un método de API, debe elegir uno como predeterminado para gestionar cualquier respuesta de integración de un código de estado no previsto. Es razonable establecer `500` como predeterminado, ya que esto equivale a emitir respuestas que de otro modo no estarían asignadas como un error del servidor. Por motivos de instrucción, la consola de API Gateway establece la respuesta `200` como la opción predeterminada. Pero puede restablecerla en la respuesta `500`. Para configurar una respuesta de método, debe haber creado la solicitud de método. ## Configurar el código de estado de la respuesta de método El código de estado de una respuesta de método define un tipo de respuesta. Por ejemplo, las respuestas de 200, 400 y 500 indican respuestas de éxito, de error del lado del cliente y de error del lado del servidor, respectivamente. Para configurar un código de estado de respuesta de método, establezca la propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode) en un código de estado HTTP. El siguiente comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) permite crear la respuesta del método `200`. ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 ``` ## Configurar parámetros de respuesta de métodos Los parámetros de respuesta de método definen qué encabezados recibe el cliente en respuesta a la solicitud de método asociado. Los parámetros de respuesta también especifican un objetivo al que API Gateway asigna un parámetro de respuesta de integración, según los mapeos prescritos en la respuesta de integración del método de la API. Para configurar los parámetros de respuesta de método, agregue al mapa [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) de `MethodResponse` pares de clave-valor con el formato `"{parameter-name}":"{boolean}"`. El siguiente comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) permite establecer el encabezado `my-header`. ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 \ --response-parameters method.response.header.my-header=false ``` ## Configurar modelos de respuesta de método Un modelo de respuesta de método define un formato del cuerpo de la respuesta del método. Es necesario configurar un modelo de respuesta de método al generar un SDK con establecimiento inflexible de tipos para la API. Garantiza que el resultado se emite en una clase apropiada en Java u Objective-C. En otros casos, la configuración de un modelo es opcional. Antes de configurar el modelo de respuesta, primero debe crear el modelo en API Gateway. Para ello, puede llamar al comando `[create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html)`. El siguiente comando [create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html) permite crear un modelo `PetStorePet` para describir el cuerpo de la respuesta para la solicitud del método `GET /pets/{petId}`. ``` aws apigateway create-model \ --rest-api-id vaz7da96z6 \ --content-type application/json \ --name PetStorePet \ --schema '{ \ "$schema": "http://json-schema.org/draft-04/schema#", \ "title": "PetStorePet", \ "type": "object", \ "properties": { \ "id": { "type": "number" }, \ "type": { "type": "string" }, \ "price": { "type": "number" } \ } \ }' ``` El resultado se crea como un recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) de API Gateway. Para configurar los modelos de respuesta de método para definir el formato de la carga, agregue el par de clave-valor "application/json":"PetStorePet" al mapa [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels) del recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). El siguiente comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) permite crear un método de respuesta que utilice un modelo de respuesta para definir el formato de carga útil: ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 \ --response-parameters method.response.header.my-header=false \ --response-models '{"application/json":"PetStorePet"}' ``` # Configuración de un método con la consola de API Gateway Al crear un método mediante la consola de la API de REST, se configuran la solicitud de integración y la solicitud del método. De forma predeterminada, API Gateway crea la respuesta del método `200` para el método. Las siguientes instrucciones muestran cómo editar la configuración de la solicitud de método y cómo crear respuestas de método adicionales para el método. **Topics** + [Edición de una solicitud de método de API Gateway en la consola de API Gateway](#how-to-method-settings-callers-console) + [Configurar una respuesta de método de API Gateway en la consola de API Gateway](#how-to-method-response-settings-console) ## Edición de una solicitud de método de API Gateway en la consola de API Gateway Estas instrucciones presuponen que ya ha creado la solicitud de método. Para obtener más información sobre cómo crear un método, consulte [Configuración de una solicitud de integración de la API mediante la consola de API Gateway](how-to-method-settings-console.md). 1. En el panel **Recursos**, elija el método y, a continuación, elija la pestaña **Solicitud de método**. 1. En la sección **Configuración de solicitud de método**, elija **Editar**. 1. En **Autorización**, seleccione un autorizador disponible. 1. Para habilitar el acceso abierto al método a cualquier usuario, elija **Ninguno**. Este paso se puede omitir si el ajuste predeterminado no se ha cambiado. 1. Para utilizar permisos de IAM para controlar el acceso de clientes al método, seleccione `AWS_IAM`. Con esta opción, solo los usuarios de los roles de IAM con la política correcta de IAM asociada pueden llamar a este método. Para crear el rol de IAM, especifique una política de acceso con un formato como el siguiente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/" ] } ] } ``` ------ En esta política de acceso, `arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/` es el ARN del método. Puede encontrar el ARN del método mediante la selección del método en la página de **Recursos**. Para obtener más información acerca de cómo establecer los permisos de IAM, consulte [Control del acceso a una API de REST con permisos de IAM](permissions.md). Para crear un rol de IAM, puede adaptar las instrucciones del siguiente tutorial, [Creación de una función de Lambda para la integración de Lambda no de proxy](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda). 1. Para usar un autorizador de Lambda, seleccione un token o un autorizador de solicitudes. Cree un autorizador de Lambda para que esta opción se muestre en el menú desplegable. Para obtener más información sobre cómo crear un autorizador de Lambda, consulte [Uso de autorizadores Lambda de API Gateway](apigateway-use-lambda-authorizer.md). 1. Para utilizar un grupo de usuarios de Amazon Cognito, elija un grupo de usuarios disponible en **Cognito user pool authorizers (Autorizadores de grupos de usuarios de Cognito)**. Cree un grupo de usuarios en Amazon Cognito y un autorizador de grupo de usuarios de Amazon Cognito en API Gateway para que esta opción se muestre en el menú desplegable. Para obtener información sobre cómo crear 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](apigateway-integrate-with-cognito.md). 1. Para especificar la validación de la solicitud, seleccione un valor en el menú desplegable **Validador de solicitudes**. Para desactivar la validación de solicitudes, seleccione **Ninguna**. Para obtener más información acerca de cada opción, consulte [Solicitud de la validación de las API de REST en API Gateway](api-gateway-method-request-validation.md). 1. Seleccione **Clave de API obligatoria** para que se requiera una clave de API. Cuando se habilita, las claves de API se utilizan en [planes de uso](api-gateway-api-usage-plans.md) para limitar el tráfico del cliente. 1. De forma opcional, para asignar un nombre de operación en un SDK de Java de esta API, generado por API Gateway, ingrese un nombre en **Nombre de operación**. Por ejemplo, para la solicitud de método de `GET /pets/{petId}`, el nombre de operación de SDK de Java correspondiente es por defecto `GetPetsPetId`. Este nombre se crea a partir del verbo HTTP del método (`GET`) y los nombres de variables de la ruta de recursos (`Pets` y `PetId`). Si establece el nombre de operación como `getPetById`, el nombre de operación de SDK pasa a ser `GetPetById`. 1. Para añadir un parámetro de cadena de consulta al método, haga lo siguiente: 1. Elija **Parámetros de cadenas de consulta de URL** y, a continuación, elija **Agregar cadena de consulta**. 1. En **Nombre**, escriba el nombre del parámetro de cadena de consulta. 1. Seleccione **Obligatorio** si el parámetro de cadena de consulta recién creado debe utilizarse para la validación de solicitudes. Para obtener más información sobre la validación de solicitud, consulte [Solicitud de la validación de las API de REST en API Gateway](api-gateway-method-request-validation.md). 1. Seleccione **Almacenamiento en caché** si el parámetro de cadena de consulta recién creado va a utilizarse como parte de una clave de almacenamiento en caché. Para obtener más información acerca del almacenamiento en caché, consulte [Usar parámetros de método o integración como claves de caché para indexar las respuestas almacenadas en caché](api-gateway-caching.md#enable-api-gateway-cache-keys). Para eliminar el parámetro de cadena de consulta, seleccione **Eliminar**. 1. Para añadir un parámetro de encabezado al método, haga lo siguiente: 1. Elija **Encabezados de solicitud HTTP** y, a continuación, elija **Agregar encabezado**. 1. En **Nombre**, ingrese el nombre del encabezado. 1. Seleccione **Obligatorio** si el encabezado recién creado debe utilizarse para la validación de solicitudes. Para obtener más información sobre la validación de solicitud, consulte [Solicitud de la validación de las API de REST en API Gateway](api-gateway-method-request-validation.md). 1. Seleccione **Almacenamiento en caché** si el encabezado recién creado va a utilizarse como parte de una clave de almacenamiento en caché. Para obtener más información acerca del almacenamiento en caché, consulte [Usar parámetros de método o integración como claves de caché para indexar las respuestas almacenadas en caché](api-gateway-caching.md#enable-api-gateway-cache-keys). Para eliminar el encabezado, elija **Eliminar**. 1. Para declarar el formato de carga de una solicitud de método con el verbo HTTP `POST`, `PUT` o `PATCH`, elija **Cuerpo de la solicitud** y realice lo siguiente: 1. Elija **Add model (Añadir modelo)**. 1. En **Content-type**, escriba un tipo de MIME (por ejemplo, `application/json`). 1. En **Modelo**, seleccione un modelo en el menú desplegable. Los modelos disponibles actualmente para la API incluyen los modelos predeterminados `Empty` y `Error`, así como cualquier modelo que haya creado y agregado a la colección [Models](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) de la API. Para obtener más información acerca de la creación de un modelo, consulte [Modelos de datos para las API de REST](models-mappings-models.md). **nota** El modelo es útil para informar al cliente del formato de datos esperado de una carga. Resulta útil para generar una plantilla de asignación de esqueleto. Es importante para generar un SDK con establecimiento inflexible de tipos de la API en idiomas como Java, C \$1, Objective-C y Swift. Solo es necesario si se habilita la validación de solicitudes frente a la carga. 1. Seleccione **Save**. ## Configurar una respuesta de método de API Gateway en la consola de API Gateway Un método de API puede tener una o más respuestas. Cada respuesta se indexa mediante su código de estado HTTP. De forma predeterminada, la consola de API Gateway agrega la respuesta `200` a las respuestas de método. Puede modificarla, por ejemplo, para que el método devuelva `201` en su lugar. Puede añadir otras respuestas, por ejemplo, `409` para la denegación de acceso y `500` para las variables de etapa sin inicializar utilizadas. Para utilizar la consola de API Gateway para modificar, eliminar o agregar una respuesta a un método de API, siga estas instrucciones. 1. En el panel de **Recursos**, elija el método y, a continuación, elija la pestaña **Respuesta de método**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. 1. En la sección **Configuración de respuesta del método**, elija **Crear respuesta**. 1. Para **Código de estado HTTP**, ingrese un código de estado HTTP como `200`, `400` o `500`. Si una respuesta devuelta del backend no tiene una respuesta de método correspondiente definida, API Gateway no puede devolver la respuesta al cliente. En su lugar, devuelve una respuesta de error `500 Internal server error`. 1. Elija **Agregar encabezado**. 1. En **Nombre del encabezado**, escriba un nombre. Para devolver un encabezado del backend al cliente, agregue el encabezado en la respuesta del método. 1. Elija **Agregar modelo** para definir un formato del cuerpo de la respuesta del método. Ingrese el tipo de medio de la carga de respuesta de **Tipo de contenido** y elija un modelo en el menú desplegable **Modelos**. 1. Seleccione **Save**. Para modificar una respuesta existente, navegue hasta la respuesta de su método y, a continuación, elija **Editar**. Para cambiar el **Código de estado HTTP**, elija **Eliminar** y cree una nueva respuesta de método. Para cada respuesta que devuelve el backend, debe tener una respuesta compatible configurada como respuesta de método. Sin embargo, los encabezados de respuesta de método de configuración y el modelo de carga son opcionales, a menos que asigne el resultado del backend a la respuesta de método antes de volver al cliente. Además, un modelo de carga de respuesta de método es importante si está generando un SDK con establecimiento inflexible de tipos para su API.