Notas importantes de Amazon API Gateway

Notas importantes de Amazon API Gateway para las API REST y de WebSocket

• API Gateway no permite compartir un nombre de dominio personalizado en las API REST y de WebSocket.

• Los nombres de etapas solo pueden contener caracteres alfanuméricos, guiones y caracteres de subrayado. La longitud máxima es de 128 caracteres.

• Las rutas /ping y /sping están reservadas para la comprobación de estado del servicio. No se producirá el resultado previsto si se usan estos recursos en el nivel de raíz de la API.

• API Gateway limita actualmente los eventos de registro a 1024 bytes. Los eventos de registros de más de 1024 bytes, como cuerpos de solicitud y respuesta, los truncará API Gateway antes de su envío a CloudWatch Logs.

• En la actualidad, las métricas de CloudWatch limitan los nombres y los valores de las dimensiones a 255 caracteres XML válidos. (Para obtener más información, consulte la guía del usuario de CloudWatch). Los valores de dimensión son una función de los nombres definidos por el usuario, incluido el nombre de API, el nombre de etiqueta (etapa) y el nombre de recurso. Cuando elija estos nombres, asegúrese de no superar los límites de las métricas de CloudWatch.

• El tamaño máximo de una plantilla de asignación es de 300 KB.

Notas importantes de Amazon API Gateway para las API de WebSocket

• API Gateway admite cargas de mensajes de hasta 128 KB con un tamaño máximo de trama de 32 KB. Si un mensaje supera los 32 KB, se debe dividir en varias tramas, cada una con tamaño máximo de 32 KB. Si se recibe un mensaje más grande, la conexión se cierra con el código 1009.

Notas importantes de Amazon API Gateway para las API REST

• El carácter de barra vertical del texto sin formato (|) no es compatible con las cadenas de las consultas URL y debe codificarse en formato URL.

• El carácter de punto y coma (;) no se admite en las cadenas de consulta URL de la solicitud ni en los resultados de los datos que se van a dividir. En general, las API de REST decodifican los parámetros de solicitud codificados con URL antes de pasarlos a las integraciones de backend.

• Cuando se utiliza la consola de API Gateway para probar una API, es posible que aparezca la respuesta "errores de punto de enlace desconocido" si un certificado autofirmado se presenta en el backend, si falta el certificado intermedio en la cadena de certificados o si el backend genera cualquier otra excepción relacionada con un certificado que no se reconoce.

• En el caso de la entidad Resource o Method de la API con una integración privada, debe eliminar estas entidades después de eliminar cualquier referencia codificada de forma rígida de VpcLink. De lo contrario, quedará una integración pendiente y aparecerá un error en el que se indicará que el enlace VPC sigue en uso aunque la entidad Resource o Method se haya eliminado. Este comportamiento no se aplica cuando la integración privada hace referencia a VpcLink a través de una variable de etapa.

• Los siguientes backends no son compatibles con la autenticación de clientes SSL con API Gateway:

  • NGINX

  • Heroku

• API Gateway admite la mayor parte de la especificación de OpenAPI 2.0 y la especificación de OpenAPI 3.0, con las siguientes excepciones:

  • Los segmentos de ruta solo pueden contener caracteres alfanuméricos, guiones, guiones bajos, puntos, comas, dos puntos y llaves. Los parámetros de la ruta deben ser segmentos de ruta separados. Por ejemplo, "resource/{path_parameter_name}" es válido; "resource{path_parameter_name}" no lo es.

  • Los nombres de modelo pueden contener únicamente caracteres alfanuméricos.

  • Para los parámetros de entrada, solo se admiten los siguientes atributos: , , , y: name, in, required, type, description. Los demás atributos se ignoran.

  • El tipo securitySchemes, si se utiliza, debe ser apiKey. Sin embargo, OAuth 2 y la autenticación de HTTP Basic se admiten a través de autorizadores de Lambda; la configuración OpenAPI se consigue a través de extensiones de proveedor.

  • El campo deprecated no es compatible y se descarta en API exportadas.

  • Los modelos de API Gateway se definen utilizando esquemas JSON, borrador 4, en lugar de los esquemas JSON que utiliza OpenAPI.

  • El parámetro discriminator no se admite en ningún objeto de esquema.

  • La etiqueta example no se admite.

  • exclusiveMinimum no es compatible con API Gateway.

  • Las etiquetas maxItems y minItems no están incluidas en la validación de solicitud sencilla. Para solucionarlo, actualice el modelo después de la importación antes de efectuar la validación.

  • oneOf no es compatible con la generación de OpenAPI 2.0 o SDK.

  • El campo readOnly no se admite.

  • $ref no puede utilizarse para hacer referencia a otros archivos.

  • Las definiciones de respuesta con el formato "500": {"$ref": "#/responses/UnexpectedError"} no se admiten en la raíz de documentos de OpenAPI. Para solucionar este problema, sustituya la referencia por el esquema insertado.

  • Los números de tipo Int32 o Int64 no se admiten. A continuación se muestra un ejemplo:

    "elementId": {
        "description": "Working Element Id",
        "format": "int32",
        "type": "number"
    }

  • El tipo de formato de número decimal ("format": "decimal") no se admite en una definición de esquema.

  • En las respuestas a métodos, la definición del esquema debe ser un tipo de objeto y no puede tener un tipo primitivo. Por ejemplo, "schema": { "type": "string"} no se admite. Sin embargo, puede solucionar este problema con el siguiente tipo de objeto:

    "schema": {
         "$ref": "#/definitions/StringResponse"
                }
    
     "definitions": {
        "StringResponse": {
          "type": "string"
        }
      }

  • API Gateway no utiliza seguridad de nivel raíz definida en la especificación OpenAPI. Por lo tanto hay que definir la seguridad en un nivel de funcionamiento para que se aplique de forma adecuada.

  • La default palabra clave no ese admite.

• API Gateway establece las siguientes restricciones y limitaciones al administrar métodos con una integración de Lambda o una integración HTTP.

  • Al procesar los nombres de encabezado y los parámetros de consulta, se distingue entre mayúsculas y minúsculas.

  • En la siguiente tabla se enumeran los encabezados que se pueden haber abandonado, reasignado o modificado al enviarse al punto de enlace de integración o desde él. En esta tabla:

    • Remapped significa que el nombre del encabezado se ha cambiado de <string> a X-Amzn-Remapped-<string>.

      Remapped Overwritten significa que el nombre del encabezado se cambia de <string> a X-Amzn-Remapped-<string> y se sobrescribe el valor.

    Nombre del encabezado	Solicitud (http/http_proxy/lambda)	Response: (Respuesta (http/http_proxy/lambda)
    Age	Paso a través	Paso a través
    Accept	Paso a través	Abandonado/Paso a través/Paso a través
    Accept-Charset	Paso a través	Paso a través
    Accept-Encoding	Paso a través	Paso a través
    Authorization	Transferencia directa *	Reasignado
    Connection	Paso a través/Paso a través/Abandonado	Reasignado
    Content-Encoding	Paso a través/Abandonado/Paso a través	Paso a través
    Content-Length	Paso a través (generado basándose en el cuerpo)	Paso a través
    Content-MD5	Abandonado	Reasignado
    Content-Type	Paso a través	Paso a través
    Date	Paso a través	Reasignado/Sobrescrito
    Expect	Abandonado	Abandonado
    Host	Sobrescrito en el punto de enlace de integración	Abandonado
    Max-Forwards	Abandonado	Reasignado
    Pragma	Paso a través	Paso a través
    Proxy-Authenticate	Abandonado	Abandonado
    Range	Paso a través	Paso a través
    Referer	Paso a través	Paso a través
    Server	Abandonado	Reasignado/Sobrescrito
    TE	Abandonado	Abandonado
    Transfer-Encoding	Abandonado/Abandonado/Excepción	Abandonado
    Trailer	Abandonado	Abandonado
    Upgrade	Abandonado	Abandonado
    User-Agent	Paso a través	Reasignado
    Via	Abandonado/Abandonado/Paso a través	Paso a través/Abandonado/Abandonado
    Warn	Paso a través	Paso a través
    WWW-Authenticate	Abandonado	Reasignado

    * El encabezado Authorization se elimina si contiene una firma Signature Version 4 o si se usa la autorización de AWS_IAM.

• El SDK de Android de una API generado por API Gateway utiliza la clase java.net.HttpURLConnection. Esta clase producirá una excepción no administrada en dispositivos con Android 4.4 y versiones anteriores si la reasignación del encabezado WWW-Authenticate a X-Amzn-Remapped-WWW-Authenticate produce una respuesta 401.

• A diferencia de los SDK de Java, Android e iOS de una API generados por API Gateway, el SDK de JavaScript de una API generado por API Gateway no admite reintentos de error de nivel 500.

• La invocación de prueba de un método utiliza el tipo de contenido predeterminado de application/json y no tiene en cuenta las especificaciones de cualquier otro tipo de contenido.

• Al enviar solicitudes a una API pasando el encabezado X-HTTP-Method-Override, API Gateway anula el método. Por lo tanto, con el fin de pasar el encabezado al backend, el encabezado tiene que añadirse a la solicitud de integración.

• Cuando una solicitud contiene varios tipos de medios en su encabezado Accept, API Gateway solo respeta el primer tipo de medio Accept. En aquella situación en la que no pueda controlar el orden de los tipos de medios Accept y el tipo de medio del contenido binario no sea el primero de la lista, puede agregar el primer tipo de medio Accept en la lista binaryMediaTypes de la API; API Gateway devolverá su contenido como binario. Por ejemplo, para enviar un archivo JPEG utilizando un elemento <img> en un navegador, el navegador puede enviar Accept:image/webp,image/*,*/*;q=0.8 en una solicitud. Al añadir image/webp a la lista binaryMediaTypes, el punto de enlace recibirá el archivo JPEG como binario.

• Actualmente, no se permite personalizar la respuesta predeterminada de la gateway en 413 REQUEST_TOO_LARGE.

• API Gateway incluye un encabezado Content-Type para todas las respuestas de integración. De forma predeterminada, el tipo de contenido es application/json.