Modelos de dados para APIs REST - Amazon API Gateway
Criar modelos mais complexosUsar modelos de dados de saídaPróximas etapas

Modelos de dados para APIs REST

No API Gateway, um modelo define a estrutura de dados de uma carga. No API Gateway, modelos são definidos usando o esquema JSON rascunho 4. O objeto JSON a seguir é uma amostra de dados no exemplo da Pet Store.

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

Os dados contêm o id, o type e o price do animal de estimação. Um modelo desses dados possibilita que você:

  • Use a validação básica da solicitação.

  • Crie modelos de mapeamento para transformação de dados.

  • Crie um tipo de dados definido pelo usuário (UDT) ao gerar um SDK.

Exemplo de modelo de dados JSON para a API PetStore.

Neste modelo:

  1. O objeto $schema representa um identificador de versão do Esquema JSON válido. Esse esquema é o rascunho do JSON Schema v4.

  2. O objeto title é um identificador humanamente legível para o modelo. Esse título é PetStoreModel.

  3. A palavra-chave de validação required exige o type e o price para validação básica da solicitação.

  4. As properties do modelo são id, type e price. Cada objeto tem propriedades que são descritas no modelo.

  5. O objeto type pode ter somente os valores dog, cat ou fish.

  6. O objeto price é um número e está limitado ao minimum de 25 e ao 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 }

Neste modelo:

  1. Na linha 2, o objeto $schema representa um identificador de versão do JSON Schema válido. Esse esquema é o rascunho do JSON Schema v4.

  2. Na linha 3, o objeto title é um identificador legível para o modelo. Esse título é PetStoreModel.

  3. Na linha 5, a palavra-chave de validação required exige o type e o price para validação básica da solicitação.

  4. Nas linhas 6 a 17, as properties do modelo são id, type e price. Cada objeto tem propriedades que são descritas no modelo.

  5. Na linha 12, o objeto type pode ter somente os valores dog, cat ou fish.

  6. Nas linhas 14 a 17, o objeto price é um número e está limitado ao minimum de 25 e ao maximum de 500.

Criar modelos mais complexos

É possível usar o $ref primitivo para criar definições reutilizáveis para modelos mais longos. Por exemplo, você pode criar uma definição chamada Price na seção definitions que descreve o objeto price. O valor de $ref é a definição 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
            }
      }
}

Você também pode referenciar outro esquema de modelo definido em um arquivo de modelo externo. Defina o valor da propriedade $ref para a localização do modelo. No exemplo a seguir, o modelo Price é definido no modelo PetStorePrice na API a1234.

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

O modelo mais longo pode referenciar o modelo 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"
    }
  }
}

Usar modelos de dados de saída

Se você transformar seus dados, poderá definir um modelo de carga útil na resposta de integração. Um modelo de carga útil pode ser usado quando você gera um SDK. Para linguagens de tipo forte, como Java, Objective-C ou Swift, o objeto corresponde a um tipo de dados definido pelo usuário (UDT). O API Gateway cria um UDT se você fornecê-lo com um modelo de dados ao gerar um SDK. Para ter mais informações sobre transformações de dados, consulte Transformações de modelo de mapeamento para APIs REST no API Gateway.

O exemplo a seguir são dados de saída de uma resposta de integração.

{
[
  {
    "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
  }
]
}

O exemplo a seguir é um modelo de payload que descreve os dados de saída.

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

Com esse modelo, você pode chamar um SDK para recuperar os valores de propriedades description e askingPrice, lendo as propriedades PetStoreOutputModel[i].description e PetStoreOutputModel[i].askingPrice. Se nenhum modelo for fornecido, o API Gateway usará o modelo vazio para criar um UDT padrão.

Próximas etapas