Modelli di dati per REST API - Amazon API Gateway
Creazione di modelli più complessiUtilizzo di modelli di dati di outputPassaggi successivi

Modelli di dati per REST API

In API Gateway, un modello definisce la struttura dei dati di un payload. In Gateway Amazon API i modelli sono definiti utilizzando lo schema JSON bozza 4. Il seguente oggetto JSON è un esempio di dati nell'esempio di Pet Store.

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

I dati contengono i valori id, type e price dell'animale domestico. Un modello di questi dati consente di:

  • Usare la convalida di base delle richieste.

  • Creare modelli di mappatura per la trasformazione dei dati.

  • Creare un tipo di dati definito dall'utente (UDT) quando viene generato un SDK.

Esempio di modello di dati JSON per l'API PetStore.

In questo modello:

  1. L'oggetto $schema rappresenta un identificatore valido della versione dello schema JSON. Questo schema è lo schema JSON bozza v4.

  2. L'oggetto title è un identificatore in formato leggibile del modello. Questo titolo è PetStoreModel.

  3. La parola chiave di convalida required richiede type e price per la convalida di base della richiesta.

  4. La variabile properties del modello è id, type eprice. Ogni oggetto ha proprietà che vengono descritte nel modello.

  5. L'oggetto type può avere solo i valori dog, cat o fish.

  6. L'oggetto price è un numero ed è vincolato con un valore minimum di 25 e un valore maximum di 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 }

In questo modello:

  1. Alla riga 2, l'oggetto $schema rappresenta un identificatore valido della versione dello schema JSON. Questo schema è lo schema JSON bozza v4.

  2. Alla riga 3, l'oggetto title è un identificatore in formato leggibile del modello. Questo titolo è PetStoreModel.

  3. Alla riga 5, la parola chiave di convalida required richiede type e price per la convalida di base della richiesta.

  4. Alle righe da 6 a 17, la variabile properties del modello è id. type e price. Ogni oggetto ha proprietà che vengono descritte nel modello.

  5. Alla riga 12, l'oggetto type può avere solo i valori dog, cat o fish.

  6. Alle righe da 14 a 17, l'oggetto price è un numero ed è vincolato con un valore minimum di 25 e un valore maximum di 500.

Creazione di modelli più complessi

È possibile utilizzare la primitiva $ref per creare definizioni riutilizzabili per modelli più lunghi. Ad esempio, è possibile creare una definizione chiamata Price nella sezione definitions che descrive l'oggetto price. Il valore di $ref è la definizione 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
            }
      }
}

È inoltre possibile fare riferimento a un altro schema del modello definito in un file di modello esterno. Impostare il valore della proprietà $ref sulla posizione del modello. Nell'esempio seguente, il modello Price è definito nel modello PetStorePrice nell'API a1234.

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

Il modello più lungo può fare riferimento al modello 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"
    }
  }
}

Utilizzo di modelli di dati di output

In caso di trasformazione dei dati, è possibile definire un modello di payload nella risposta dell'integrazione. È possibile utilizzare un modello di payload quando si genera un SDK. Per linguaggi fortemente tipizzati, come Java, Objective-C o Swift, l'oggetto corrisponde a un tipo di dati definito dall'utente (UDT). Gateway Amazon API crea un tipo di dati definito dall'utente se viene specificato con un modello di dati durante la generazione di un SDK. Per ulteriori informazioni sulle trasformazioni dei dati, consultare Trasformazioni dei modelli di mappatura per REST API in Gateway API.

L'esempio seguente indica i dati di output di una risposta di integrazione.

{
[
  {
    "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'esempio seguente indica un modello di payload che descrive i dati di output.

{
"$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
    }
  }
}

Con questo modello, è possibile eseguire una chiamata a un SDK per recuperare i valori delle proprietà description, askingPrice leggendo le proprietà PetStoreOutputModel[i].description e PetStoreOutputModel[i].askingPrice. Se non viene fornito alcun modello, API Gateway utilizzerà il modello vuoto per creare un UDT predefinito.

Passaggi successivi