¿Cómo se asignan códigos de estado de respuesta para las integraciones de API Gateway en las API de REST?

Resolución

Cuando quiera anular los códigos de estado de respuesta de su backend, utilice expresiones regulares o plantillas de asignación de API Gateway para asignar los códigos de estado. Puede hacerlo en integraciones con proxy y sin proxy con la API de REST.

Las integraciones con proxy y sin proxy se utilizan para asignar los códigos de estado de respuesta en la API de REST. Cuando hay una respuesta del proxy, API Gateway recibe los códigos de estado tal como los envía el backend. En una integración de proxy de Lambda, API Gateway requiere que la función de Lambda del backend devuelva el siguiente resultado en formato JSON:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode, 
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": “…”65411
}

En una integración de proxy con una función de Lambda, se pasa un código de estado directamente a API Gateway desde una función de Lambda de backend. No se puede pasar un código de estado directamente desde la función de Lambda en una integración sin proxy.

Cuando API Gateway invoca correctamente una función de Lambda, el código de estado de respuesta predeterminado es 200. Los códigos de estado también se devuelven cuando Lambda experimenta errores. Puede personalizar los códigos de respuesta de API Gateway. Utilice una integración sin proxy y una plantilla de asignación cuando tenga que crear un código de respuesta personalizado.

Configuración de un método de respuesta con código personalizado

Siga estos pasos para configurar un método que responda con un código de respuesta personalizado desde API Gateway:

1.    En la consola de API Gateway, cree una API de REST pública.

2.    Cree un recurso y un método para el recurso.

3.    Configure una respuesta de método que incluya el código de estado que quiere que devuelva API Gateway.

4.    Configure una respuesta de integración de Lambda.

• Para Lambda Error Regex (Expresión regular de errores de Lambda), proporcione el patrón de expresión regular para el mensaje de error devuelto por la función de Lambda.
  Nota: También puede encontrar la expresión regular de errores HTTP para las respuestas HTTP.
• Para el estado de respuesta del método, proporcione el código de estado que debe devolver API Gateway.
• Elija una opción de Content Handling (Gestión de contenido) para establecer cómo se gestiona el cuerpo de la respuesta antes de enviar la respuesta al cliente.
• Asegúrese de que el patrón predeterminado del código de estado esté establecido en 200.

5.    Cuando termine de configurar la respuesta de integración, guarde, pruebe e implemente los cambios.

Asignación de códigos de estado a valores estáticos

Para que API Gateway capture un grupo de códigos de estado devueltos desde el backend, asigne los códigos de estado a valores estáticos:

1.    Vaya al recurso que tiene el código de estado que quiere cambiar.

2.    Configure una respuesta de método para que devuelva 400 como código de respuesta de API Gateway.

3.    Vuelva a las configuraciones de los recursos y establezca una respuesta de integración.

4.    Los valores de HTTP status regex (Expresión regular de estado HTTP) capturan el estado devuelto por el backend. A continuación, el estado se asigna al código de respuesta definido en el paso 2.

Cuando HTTP status regex (Expresión regular de estado HTTP) tiene un valor predeterminado de «-» y se asigna a 200 como estado de respuesta del método, la asignación de backend captura todos los códigos de estado y los devuelve a 200. Puede cambiar los valores de HTTP status regex (Expresión regular de estado HTTP) a 2\d{2} para capturar todas las respuestas 2xx y asignarlas a 200.

5.    Elija Add integration response (Agregar respuesta de integración) para capturar los demás códigos de estado.

Para 4xx, en HTTP status regex (Expresión regular de estado HTTP), agregue 4\d{2}. En Method response status (Estado de respuesta del método), elija 400. Esto se definió en el paso 2.

6.    Implemente la API. Cuando la API devuelve cualquier código de estado 2xx, se asigna al código de estado 200. Si la API devuelve algún código de estado 4xx, se asigna al código de estado 400.

Las expresiones regulares pueden tener muchos formatos distintos. Por ejemplo:

• .*([01][0-9][0-9]|2[0-4][0-9]|25[0-5]).* coincide con los códigos de estado entre 100-199, 200-249 o 250-255.
• .*5\d\d.* coincide con un código de estado, como 5xx.

El siguiente código de ejemplo sirve para probar una función de Lambda:

def lambda_handler(event, context):
    if "error" not in event or event['error'] == "":
        return("Pass")
    elif event['error'] == 'sample 400':
        raise Exception({"errorMessage": "Error: Raising 400 from within the Lambda function","errorType": "Exception"})
    elif event['error'] == 'sample 500':
        raise Exception({"errorMessage": "Error: Raising 500 from within the Lambda function","errorType": "Exception"})
    else:
        return("Error Value in the json request should either be 400 or 500 to demonstrate")

En el ejemplo, el código comprueba si el valor de error enviado desde API Gateway es un error 400 o 500. Cuando se trata de un error 400 o 500, el código de Lambda genera una excepción con un mensaje de error. Cuando API Gateway recibe la respuesta, el servicio comprueba si el mensaje de error coincide con algún patrón configurado en la respuesta de integración. API Gateway responde en consecuencia si el patrón de expresiones regulares de Lambda coincide.

7.    Tras una configuración correcta, los códigos de estado se pueden probar mediante la consola de API Gateway.

Asignación de códigos de estado con plantillas de asignación

En el ejemplo anterior se usan expresiones regulares, pero también se pueden usar plantillas de asignación. El siguiente ejemplo anula el código de estado 200 del backend para aplicar el código de estado 400:

1.    Cree una función de Lambda con el siguiente código de ejemplo:

----------------------
def lambda_handler(event, context):
    # TODO implement print(event)
    return { 'statusCode': 200, 'body': "customerror" }
-----------------------

2.    Cree una API con una integración sin proxy de Lambda mediante la función de Lambda anterior para el backend.

3.    Siga los pasos del 6 al 10 descritos en el tutorial Cómo anular el código de estado de respuesta de una API con el tutorial de la consola de API Gateway.

En este ejemplo, utilice la siguiente plantilla de asignación:

----------------------
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("customerror"))
#set($context.responseOverride.status = 400)
#end 
----------------------

4.    Guarde, pruebe e implemente la API.

---

Información relacionada

Trabajar con modelos y plantillas de asignación

Transformación de las solicitudes y respuestas de API

Guía de desarrollador de Amazon API Gateway