Remarques importantes concernant Amazon API Gateway - Amazon API Gateway
Remarques importantes concernant Amazon API Gateway pour les API HTTPRemarques importantes concernant Amazon API Gateway pour les API HTTP et WebSocketRemarques importantes pour les API REST et WebSocketRemarques importantes pour les API WebSocketRemarques importantes pour les API REST

Remarques importantes concernant Amazon API Gateway

La section suivante détaille les remarques susceptibles d’avoir un impact sur votre façon d’utiliser API Gateway.

Remarques importantes concernant Amazon API Gateway pour les API HTTP

  • Les API HTTP traduisent les en-têtes X-Forwarded-* entrants en en-têtes Forwarded standard et ajoutent l’adresse IP, l’hôte et le protocole de sortie.

  • API Gateway ajoute l’en-tête Content-type à votre demande s’il n’y a pas de données utiles et si Content-Length est égal à 0.

Remarques importantes concernant Amazon API Gateway pour les API HTTP et WebSocket

  • Amazon API Gateway ne prend pas officiellement en charge Signature Version 4A pour les API HTTP et WebSocket.

Remarques importantes concernant Amazon API Gateway pour les API REST et WebSocket

  • API Gateway ne prend pas en charge le partage d’un nom de domaine personnalisé dans les API REST et WebSocket.

  • Les noms d’étape peuvent contenir uniquement des caractères alphanumériques, des tirets et des traits de soulignement. La longueur maximale est de 128 caractères.

  • Les chemins d’accès /ping et /sping sont réservés à la vérification de l’état du service. L’utilisation de ces chemins pour les ressources racine de l’API avec des domaines personnalisés ne permet pas d’obtenir le résultat attendu.

  • API Gateway limite actuellement les évènements de journaux à 1 024 octets. Les événements de journaux de plus de 1 024 octets, tels que les corps de demandes et de réponses, seront tronqués par API Gateway avant leur envoi à CloudWatch Logs.

  • CloudWatch Metrics limite actuellement les noms et les valeurs de dimension à 255 caractères XML valides. (Pour plus d’informations, consultez le Guide de l’utilisateur CloudWatch.) Les valeurs de dimension sont une fonction des noms définis par l’utilisateur, y compris le nom de l’API, le nom de l’étiquette (étape) et le nom de la ressource. Lorsque vous choisissez ces noms, prenez garde de ne pas dépasser les limites CloudWatch Metrics.

  • La taille maximale d’un modèle de mappage est de 300 Ko.

Remarques importantes concernant Amazon API Gateway pour les API WebSocket

  • API Gateway prend en charge des charges utiles de messages jusqu’à 128 Ko, avec une taille de trame maximale de 32 Ko. Si un message dépasse 32 Ko, vous devez le diviser en plusieurs trames, chacune de 32 Ko ou moins. Si un message plus grand est reçu, la connexion se ferme avec le code 1009.

Remarques importantes concernant Amazon API Gateway pour les API REST

  • Le caractère pipe en texte brut (|) et l’accolade ({ ou }) ne sont pas pris en charge pour les chaînes de requête des URL de demande et doit être encodé en URL.

  • Le caractère point-virgule (;) n’est pas pris en charge pour les chaînes de requête d’URL et entraîne le fractionnement des données.

  • Les API REST décodent les paramètres de demande encodés en URL avant de les transmettre aux intégrations backend. Pour les paramètres de demande UTF-8, les API REST décodent les paramètres, puis les transmettent au format Unicode aux intégrations backend. Les API REST encodent en URL le caractère de pourcentage (%) avant de le transmettre aux intégrations backend.

  • Lorsque vous utilisez la console API Gateway pour tester une API, vous pouvez recevoir une réponse de type « erreurs de point de terminaison inconnu » si un certificat auto-signé est présenté au backend, si le certificat intermédiaire est absent de la chaîne de certificats ou si toute autre exception liée à un certificat non reconnaissable est déclenchée par le backend.

  • Pour les entités d’API Resource ou Method avec une intégration privée, vous devez les supprimer après avoir supprimé toute référence codée en dur de VpcLink. Dans le cas contraire, vous disposez d’une intégration instable et recevez une erreur indiquant que le lien du VPC est toujours actif même lorsque l’entité Resource ou Method est supprimée. Ce comportement ne s’applique pas lorsque l’intégration privée renvoie à VpcLink par le biais d’une variable d’étape.

  • Les backends suivants peuvent ne pas prendre en charge l’authentification de client SSL d’une manière compatible avec API Gateway :

  • API Gateway prend en charge la majeure partie de la spécification OpenAPI 2.0 et de la spécification OpenAPI 3.0, avec les exceptions suivantes :

    • Les segments de chemin peuvent contenir uniquement des caractères alphanumériques, des tirets, des points, des virgules, des doubles points et des accolades. Les paramètres de chemin doivent être des segments de chemin distincts. Par exemple, « resource/{path_parameter_name} » est valide ; « resource{path_parameter_name} » ne l’est pas.

    • Les noms de modèle ne peuvent contenir que des caractères alphanumériques.

    • Pour les paramètres d’entrée, seuls les attributs suivants sont pris en charge: name, in, required, type, description. Les autres attributs sont ignorés.

    • S’il est utilisé, le type securitySchemes doit être apiKey. Toutefois, l’authentification OAuth 2 et l’authentification de base HTTP sont prises en charge par l’intermédiaire des mécanismes d’autorisation Lambda ; les extensions fournisseur permettent de réaliser la configuration OpenAPI.

    • Le champ deprecated n’est pas pris en charge et est supprimé dans les API exportées.

    • Les modèles API Gateway sont définis à l’aide du schéma JSON version 4, plutôt que de celui utilisé par OpenAPI.

    • Le paramètre discriminator n’est pris en charge dans aucun objet de schéma.

    • La balise example n’est pas prise en charge.

    • Le champ nullable n’est pas pris en charge.

    • exclusiveMinimum n’est pas pris en charge par API Gateway.

    • Les balises maxItems et minItems ne sont pas incluses dans une validation de demande simple. Pour contourner ce problème, mettez à jour le modèle après l’importation avant d’effectuer la validation.

    • Pour OpenAPI 3.0, oneOf, anyOf et allOf ne peuvent pas utiliser $ref dans une définition du même schéma. Vous pouvez soit saisir directement votre schéma, soit définir une ressource de modèle API Gateway distincte. Pour plus d’informations, consultez Création de modèles plus complexes.

    • oneOf n’est pas pris en charge pour la génération d’OpenAPI 2.0 ou du kit SDK.

    • Le champ readOnly n’est pas pris en charge.

    • $ref ne peut pas être utilisé pour référencer d’autres fichiers.

    • Les définitions de réponse sous la forme "500": {"$ref": "#/responses/UnexpectedError"} ne sont pas prises en charge dans la racine du document OpenAPI. Pour contourner ce problème, remplacez la référence par le schéma en ligne.

    • Les nombres de type Int32 ou Int64 ne sont pas pris en charge. Voici un exemple :

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

    • Le type de format décimal ("format": "decimal") n’est pas pris en charge dans une définition de schéma.

    • Dans les réponses de méthode, la définition de schéma doit être de type objet et ne peut pas avoir l’un des types primitifs. Par exemple, "schema": { "type": "string"} n’est pas pris en charge. Cependant, vous pouvez contourner ce problème à l’aide du type d’objet suivant :

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

 "definitions": {
    "StringResponse": {
      "type": "string"
    }
  }

    • API Gateway n’utilise pas la sécurité de niveau racine définie dans la spécification OpenAPI. Par conséquent, la sécurité doit être définie au niveau de l’opération pour être appliquée correctement.

    • Le mot-clé default n’est pas pris en charge.

  • API Gateway adopte les restrictions et limitations suivantes lors de la gestion des méthodes avec intégration Lambda ou HTTP.

    • Les noms d’en-tête et les paramètres de requête sont traités de manière sensible à la casse.

    • Le tableau suivant répertorie les en-têtes qui peuvent être abandonnés, remappés ou modifiés autrement lorsqu’ils sont envoyés au point de terminaison d’intégration ou renvoyés par le point de terminaison d’intégration. Dans ce tableau :

      • Remapped signifie que le nom d’en-tête <string> est remplacé par X-Amzn-Remapped-<string>.

        Remapped Overwritten signifie que le nom d’en-tête <string> est remplacé par X-Amzn-Remapped-<string> et que la valeur est écrasée.

      Nom de l’en-tête Requête (http/http_proxy/lambda) Réponse (http/http_proxy/lambda)
      Age Transmettre Transmettre
      Accept Transmettre Abandonné/Transmettre/Transmettre
      Accept-Charset Transmettre Transmettre
      Accept-Encoding Transmettre Transmettre
      Authorization Transmettre * Remappé
      Connection Transmettre/Transmettre/Abandonné Remappé
      Content-Encoding Transmettre/Abandonné/Transmettre Transmettre
      Content-Length Transmette (généré sur la base du corps) Transmettre
      Content-MD5 A abandonné Remappé
      Content-Type Transmettre Transmettre
      Date Transmettre Remappé écrasé
      Expect A abandonné A abandonné
      Host Remplacé au point de terminaison d’intégration A abandonné
      Max-Forwards A abandonné Remappé
      Pragma Transmettre Transmettre
      Proxy-Authenticate A abandonné A abandonné
      Range Transmettre Transmettre
      Referer Transmettre Transmettre
      Server A abandonné Remappé écrasé
      TE A abandonné A abandonné
      Transfer-Encoding Abandonné/Abandonné/Exception A abandonné
      Trailer A abandonné A abandonné
      Upgrade A abandonné A abandonné
      User-Agent Transmettre Remappé
      Via Abandonné/Abandonné/Transmettre Transmettre/Abandonné/Abandonné
      Warn Transmettre Transmettre
      WWW-Authenticate A abandonné Remappé

      * L’en-tête Authorization est supprimé s’il contient une signature Signature Version 4 ou si une autorisation AWS_IAM est utilisée.

  • Le kit SDK Android d’une API générée par API Gateway utilise la classe java.net.HttpURLConnection. Cette classe lève une exception non prise en charge, sur les appareils Android 4.4 et version antérieures, dans le cas d’une réponse 401 résultant du remappage de l’en-tête WWW-Authenticate en X-Amzn-Remapped-WWW-Authenticate.

  • Contrairement aux kits SDK Java, iOS et Android générés par API Gateway, le kit SDK JavaScript d’une API générée par API Gateway ne prend pas en charge les nouvelles tentatives pour les erreurs de niveau 500.

  • Le test d’appel d’une méthode utilise le type de contenu application/json par défaut et ignore les spécifications de tous les autres types de contenu.

  • Lorsque vous envoyez des demandes à une API en transmettant l’en-tête X-HTTP-Method-Override, API Gateway remplace la méthode. Par conséquent, pour que l’en-tête soit transmis au backend, elle doit être ajoutée à la demande d’intégration.

  • Lorsqu’une demande contient plusieurs types de supports dans son en-tête Accept, API Gateway respecte uniquement le premier type de support Accept. Lorsque vous ne pouvez pas contrôler l’ordre des types de supports Accept et que le type de support de votre contenu binaire n’est pas le premier de la liste, vous pouvez ajouter le premier type de support Accept dans la liste binaryMediaTypes de votre API. API Gateway retourne alors votre contenu sous forme binaire. Par exemple, pour envoyer un fichier JPEG en utilisant un élément <img> dans un navigateur, ce dernier peut envoyer Accept:image/webp,image/*,*/*;q=0.8 dans une demande. Si vous ajoutez image/webp à la liste binaryMediaTypes, le point de terminaison reçoit le fichier JPEG sous forme binaire.

  • La personnalisation de la réponse de passerelle par défaut pour 413 REQUEST_TOO_LARGE n’est actuellement pas prise en charge.

  • API Gateway inclut un en-tête Content-Type pour toutes les réponses d’intégration. Par défaut, le type de contenu est application/json.