Modèles de données pour les API REST - Amazon API Gateway
Création de modèles plus complexesUtilisation de modèles de données de sortieÉtapes suivantes

Modèles de données pour les API REST

Dans API Gateway, un modèle définit la structure de données d’une charge utile. Dans API Gateway, les modèles sont définis à l’aide du schéma JSON version 4. L’objet JSON suivant est un exemple de données figurant dans l’exemple d’animalerie.

{
    "id": 1,
    "type": "dog",
    "price": 249.99
}

Les données contiennent les éléments id, type et price de l’animal de compagnie. Un modèle de ces données vous permet de :

  • Utiliser la validation de base des demandes.

  • Créer des modèles de mappage pour la transformation des données.

  • Créer un type de données défini par l’utilisateur (UDT) lorsque vous générez un kit SDK.

Exemple de modèle de données JSON pour l’API PetStore.

Dans ce modèle :

  1. L’objet $schema représente un identifiant de version de schéma JSON valide. Ce schéma est le brouillon de schéma JSON version 4.

  2. L’objet title est un identifiant du modèle lisible à l’œil. Ce titre est PetStoreModel.

  3. Le mot clé de validation required requiert type et price pour la validation de base des demandes.

  4. Les propriétés (properties) du modèle sont id, type et price. Chaque objet possède des propriétés qui sont décrites dans le modèle.

  5. L’objet type ne peut avoir que les valeurs dog, cat ou fish.

  6. L’objet price est un nombre limité entre un minimum de 25 et un maximum de 500.

1 {
2 "$schema": "http://json-schema.org/draft-04/schema#",
3  "title": "PetStoreModel",
4  "type" : "object",
5  "required" : [ "price", "type" ],
6  "properties" : {
7    "id" : {
8      "type" : "integer"
9    },
10    "type" : {
11      "type" : "string",
12      "enum" : [ "dog", "cat", "fish" ]
13    },
14    "price" : {
15      "type" : "number",
16      "minimum" : 25.0,
17      "maximum" : 500.0
18    }
19  }
20 }

Dans ce modèle :

  1. Ligne 2, l’objet $schema représente un identifiant de version de schéma JSON valide. Ce schéma est le brouillon de schéma JSON version 4.

  2. Ligne 3, l’objet title est un identifiant lisible du modèle. Ce titre est PetStoreModel.

  3. Ligne 5, le mot clé de validation required requiert type et price pour la validation de base des demandes.

  4. Lignes 6 à 17, les propriétés (properties) du modèle sont id, type et price. Chaque objet possède des propriétés qui sont décrites dans le modèle.

  5. Ligne 12, l’objet type ne peut avoir que les valeurs dog, cat ou fish.

  6. Lignes 14 à 17, l’objet price est un nombre limité entre un minimum de 25 et un maximum de 500.

Création de modèles plus complexes

Vous pouvez utiliser la primitive $ref pour créer des définitions réutilisables pour des modèles plus longs. Par exemple, vous pouvez créer une définition appelée Price dans la section definitions décrivant l’objet price. La valeur de $ref est la définition Price. 

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "PetStoreModelReUsableRef",
  "required" : ["price", "type" ],
  "type" : "object",
  "properties" : {
    "id" : {
      "type" : "integer"
    },
    "type" : {
      "type" : "string",
      "enum" : [ "dog", "cat", "fish" ]
    },
    "price" : {
        "$ref": "#/definitions/Price"
    }
  },
  "definitions" : {
      "Price": {
        "type" : "number",
        "minimum" : 25.0,
        "maximum" : 500.0
            }
      }
}

Vous pouvez également référencer un autre schéma de modèle défini dans un fichier de modèle externe. Définissez la valeur de la propriété $ref en fonction de l’emplacement du modèle. Dans l’exemple suivant, le modèle Price est défini dans le modèle PetStorePrice dans l’API a1234.

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "PetStorePrice",
  "type": "number",
  "minimum": 25,
  "maximum": 500
}

Le modèle le plus long peut référencer le modèle PetStorePrice.

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "PetStoreModelReusableRefAPI",
  "required" : [ "price", "type" ],
  "type" : "object",
  "properties" : {
    "id" : {
      "type" : "integer"
    },
    "type" : {
      "type" : "string",
      "enum" : [ "dog", "cat", "fish" ]
    },
    "price" : {
        "$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice"
    }
  }
}

Utilisation de modèles de données de sortie

Si vous transformez vos données, vous pouvez définir un modèle de charge utile dans la réponse d’intégration. Un modèle de charge utile peut être utilisé lorsque vous générez un kit SDK. Pour les langages fortement typés, comme Java, Objective-C ou Swift, l’objet correspond à un type de données défini par l’utilisateur (UDT). API Gateway crée un type UDT si vous lui fournissez un modèle de données lorsque vous générez un kit SDK. Pour plus d’informations sur les transformations de données, consultez Transformations de modèles de mappage pour les API REST dans API Gateway.

L’exemple suivant présente les données de sortie d’une réponse d’intégration.

{
[
  {
    "description" : "Item 1 is a dog.",
    "askingPrice" : 249.99
  },
  {
    "description" : "Item 2 is a cat.",
    "askingPrice" : 124.99
  },
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }
]
}

L’exemple suivant est un modèle de données utiles qui décrit les données de sortie.

{
"$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PetStoreOutputModel",
  "type" : "object",
  "required" : [ "description", "askingPrice" ],
  "properties" : {
    "description" : {
      "type" : "string"
    },
    "askingPrice" : {
      "type" : "number",
      "minimum" : 25.0,
      "maximum" : 500.0
    }
  }
}

Avec ce modèle, vous pouvez appeler un kit SDK pour récupérer les valeurs des propriétés description et askingPrice en lisant les propriétés PetStoreOutputModel[i].description et PetStoreOutputModel[i].askingPrice. Si aucun modèle n’est fourni, API Gateway utilise le modèle vide pour créer un type UDT par défaut.

Étapes suivantes