Remarques importantes concernant Amazon API Gateway

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 de plus amples informations, veuillez consulter 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 (|) n'est pas pris en charge pour les chaînes de requête de l'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. En général, les API REST décodent les paramètres de demande encodés en URL avant de les 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 :

  • NGINX

  • Heroku

• API Gateway prend en charge la majeur 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.

  • 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.

  • 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 transmise 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.