Notas importantes do Amazon API Gateway

A seção a seguir detalha as observações que podem afetar o uso do API Gateway.

Observações importantes do Amazon API Gateway para APIs REST, APIs HTTP e APIs de WebSocket

• A versão 4A do Signature não é oficialmente compatível com o Amazon API Gateway.

Observações importantes sobre o Amazon API Gateway para APIs HTTP

• As APIs HTTP convertem os cabeçalhos X-Forwarded-* de entrada em um cabeçalho Forwarded padrão e anexam o IP de saída, o host e o protocolo.

Notas importantes do Amazon API Gateway para APIs REST e WebSocket

• O API Gateway não é compatível com o compartilhamento de um nome de domínio personalizado em APIs REST e WebSocket.

• Nomes de estágio podem conter apenas caracteres alfanuméricos, hífens e sublinhados. O tamanho máximo é de 128 caracteres.

• Os caminhos /ping e /sping são reservados para a verificação de integridade do serviço. O uso desses recursos em nível raiz da API com domínios personalizados não conseguirá produzir o resultado esperado.

• No momento, o API Gateway limita os eventos de log a 1.024 bytes. Eventos de log maiores do que 1024 bytes, como corpos de solicitação e resposta, serão truncados pelo API Gateway antes do envio para o CloudWatch Logs.

• Atualmente, as métricas do CloudWatch limitam os nomes e valores de dimensão a 255 caracteres XML válidos. (Para obter mais informações, consulte o Guia do usuário do CloudWatch.) Os valores de dimensão são uma função de nomes definidos pelo usuário, incluindo o nome da API, o nome do rótulo (estágio) e o nome do recurso. Ao escolher esses nomes, tenha cuidado para não exceder os limites de métricas do CloudWatch.

• O tamanho máximo de um modelo de mapeamento é de 300 KB.

Notas importantes do Amazon API Gateway para APIs WebSocket

• O API Gateway é compatível com cargas de mensagem de até 128 KB com quadros no tamanho máximo de 32 KB. Se uma mensagem exceder 32 KB, é necessário dividi-la em vários quadros, cada qual contendo 32 KB ou menos. Se uma mensagem maior for recebida, a conexão será encerrada com o código 1009.

Notas importantes do Amazon API Gateway para APIs REST

• O caractere pipe de texto simples (|) não tem suporte para nenhuma solicitação de sequência de consulta de URL e deve ser codificado pela URL.

• O caractere ponto-e-vírgula (;) não tem suporte para nenhuma string de consulta de URL da solicitação e resulta nos dados divididos.

• As APIs REST decodificam parâmetros de solicitação codificados em URL antes de transmiti-los para integrações de back-end. Para parâmetros de solicitação UTF-8, as APIs REST decodificam os parâmetros, depois os transmitem como unicode para integrações de back-end.

• Ao usar o console do API Gateway para testar uma API, você pode obter a resposta “unknown endpoint errors” (erros de endpoint desconhecido) se um certificado autoassinado for apresentado ao backend, o certificado intermediário estiver ausente da cadeia de certificados ou qualquer outra exceção relacionada a certificados irreconhecíveis for lançada pelo backend.

• Para uma entidade Resource ou Method da API com integração privada, é necessário excluí-la depois de remover as referências codificadas permanentemente de um VpcLink. Caso contrário, sua integração será suspensa e você receberá uma mensagem de erro informando que o link da VPC ainda está em uso, mesmo se a entidade Resource ou Method tiver sido excluída. Esse comportamento não se aplica quando a integração privada faz referência ao VpcLink por meio de uma variável de estágio.

• Os backends a seguir podem não ser compatíveis com a autenticação de cliente SSL de uma forma que seja compatível com o API Gateway:

  • NGINX

  • Heroku

• O API Gateway é compatível com a maior parte da especificação do OpenAPI 2.0 e da especificação do OpenAPI 3.0, com as seguintes exceções:

  • Segmentos de caminho só podem conter caracteres alfanuméricos, sublinhados, hifens, pontos, vírgulas, dois-pontos e chaves. Parâmetros de caminho devem ser segmentos de caminho separados. Por exemplo, "resource/{path_parameter_name}" é válido; "resource{path_parameter_name}" não é.

  • Nomes de modelo podem conter apenas caracteres alfanuméricos.

  • Para parâmetros de entrada, somente os atributos a seguir são compatíveis: name, in, required, type, description. Outros atributos são ignorados.

  • Se usado, o tipo securitySchemes deverá ser apiKey. No entanto, OAuth 2 e autenticação básica HTTP são compatíveis por meio de autorizadores do Lambda; a configuração do OpenAPI é obtida por meio de extensões do fornecedor.

  • O campo deprecated não tem suporte e é descartado em APIs exportadas.

  • Os modelos do API Gateway são definidos usando esquema JSON rascunho 4 em vez do esquema JSON usado pelo OpenAPI.

  • O parâmetro discriminator não tem suporte em nenhum objeto de esquema.

  • Não há suporte para a tag example.

  • exclusiveMinimum não é compatível com o API Gateway.

  • As marcas maxItems e minItems não estão incluídas na validação de solicitação simples. Para resolver esse problema, atualize o modelo após a importação, antes de fazer a validação.

  • oneOf não é compatível com OpenAPI 2.0 ou a geração de SDK.

  • Não há suporte para o campo readOnly.

  • $ref não pode ser usado para referenciar outros arquivos.

  • Definições de resposta do formulário "500": {"$ref": "#/responses/UnexpectedError"} não têm suporte na raiz do documento do OpenAPI. Para contornar esse problema, substitua a referência pelo esquema embutido.

  • Não há suporte para números do tipo Int32 ou Int64. Um exemplo é mostrado conforme a seguir:

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

  • O tipo de formato de número decimal ("format": "decimal") não tem suporte em uma definição de esquema.

  • Em respostas de método, a definição de esquema deve ser de um tipo de objeto e não pode ser de tipos primitivos. Por exemplo, não há suporte para "schema": { "type": "string"}. No entanto, você pode contornar esse problema usando o seguinte tipo de objeto:

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

  • O API Gateway não usa segurança no nível raiz definida na especificação do OpenAPI. Portanto, é necessário definir a segurança em um nível de operação a ser adequadamente aplicado.

  • A palavra-chave default não é compatível.

• O API Gateway impõe as seguintes restrições e limitações ao lidar com métodos com a integração do Lambda ou a integração HTTP.

  • Os nomes de cabeçalho e parâmetros de consulta são processados em uma forma com distinção entre letras maiúsculas e minúsculas.

  • A tabela a seguir lista os cabeçalhos que podem ser descartados, remapeados ou modificados quando enviados ao seu endpoint de integração ou enviados de volta pelo seu endpoint de integração. Nesta tabela:

    • Remapped significa que o nome de cabeçalho é alterado de <string> para X-Amzn-Remapped-<string>.

      Remapped Overwritten significa que o nome de cabeçalho é alterado de <string> para X-Amzn-Remapped-<string> e o valor é substituído.

    Nome do cabeçalho	Solicitação (http/http_proxy/lambda)	Resposta (http/http_proxy/lambda)
    Age	Passagem	Passagem
    Accept	Passagem	Descartado/Passagem/Passagem
    Accept-Charset	Passagem	Passagem
    Accept-Encoding	Passagem	Passagem
    Authorization	Passagem *	Remapeado
    Connection	Descartado/Passagem/Descartado	Remapeado
    Content-Encoding	Passagem/Descartado/Passagem	Passagem
    Content-Length	Passagem (gerada com base no corpo)	Passagem
    Content-MD5	Descartado	Remapeado
    Content-Type	Passagem	Passagem
    Date	Passagem	Remapeado substituído
    Expect	Descartado	Descartado
    Host	Substituído no endpoint de integração	Descartado
    Max-Forwards	Descartado	Remapeado
    Pragma	Passagem	Passagem
    Proxy-Authenticate	Descartado	Descartado
    Range	Passagem	Passagem
    Referer	Passagem	Passagem
    Server	Descartado	Remapeado substituído
    TE	Descartado	Descartado
    Transfer-Encoding	Descartado/Descartado/Exceção	Descartado
    Trailer	Descartado	Descartado
    Upgrade	Descartado	Descartado
    User-Agent	Passagem	Remapeado
    Via	Descartado/Descartado/Passagem	Passagem/Descartado/Descartado
    Warn	Passagem	Passagem
    WWW-Authenticate	Descartado	Remapeado

    * O cabeçalho Authorization será descartado se contiver uma assinatura do Signature versão 4 ou se a autorização AWS_IAM for usada.

• O SDK do Android de uma API gerada pelo API Gateway usa a classe java.net.HttpURLConnection. Essa classe lançará uma exceção sem tratamento, em dispositivos executando o Android 4.4 e anteriores, para uma resposta 401 resultante do remapeamento do cabeçalho WWW-Authenticate para X-Amzn-Remapped-WWW-Authenticate.

• Diferentemente dos SDKs Java, Android e iOS gerados pelo API Gateway de uma API, o SDK JavaScript de uma API gerada pelo API Gateway não é compatível com a novas tentativas para erros de nível 500.

• A invocação de teste de um método usa o tipo de conteúdo padrão de application/json e ignora especificações de todos os outros tipos de conteúdo.

• Ao enviar solicitações para uma API transmitindo o cabeçalho X-HTTP-Method-Override, o API Gateway substituirá o método. Portanto, para transmitir o cabeçalho ao backend, o cabeçalho precisa ser adicionado à solicitação de integração.

• Quando uma solicitação contém vários tipos de mídia em seu cabeçalho Accept, o API Gateway apenas respeita o primeiro tipo de mídia Accept. Na situação em que você não pode controlar a ordem dos tipos de mídia de Accept e o tipo de mídia do seu conteúdo binário não é o primeiro da lista, é possível adicionar o primeiro tipo de mídia Accept na lista binaryMediaTypes da sua API, e o API Gateway retornará seu conteúdo como binário. Por exemplo, para enviar um arquivo JPEG usando um elemento <img> em um navegador, o navegador pode enviar Accept:image/webp,image/*,*/*;q=0.8 em uma solicitação. Ao adicionar image/webp à lista, o endpoint binaryMediaTypes receberá o arquivo JPEG como binário.

• A personalização da resposta de gateway padrão para 413 REQUEST_TOO_LARGE não é compatível no momento.

• O API Gateway inclui um cabeçalho Content-Type para todas as respostas de integração. Por padrão, o tipo de conteúdo é application/json.