Como associo um modelo de dados à minha API REST no API Gateway?

Resolução

Para associar um modelo de dados a uma API REST no API Gateway, conclua as etapas a seguir.

Grave um esquema de modelo para associar à sua API REST

Observação: os modelos do API Gateway devem usar o rascunho 4 do esquema JSON. Para obter mais informações sobre como gravar um esquema de modelo, consulte Modelos de dados para APIs REST.

Exemplo de esquema de modelo

Esse modelo de exemplo usa application/json como a chave padrão para selecionar o modelo de mapeamento. Seu esquema deve obedecer às seguintes condições:

• Os usuários da API devem informar seus valores de UserID e Name no corpo da solicitação.
• Os valores de UserID e Name devem ser valores de string.
• O valor de Age deve ser um valor inteiro de 18 ou maior.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "User",
  "type": "object",
  "properties": {
    "UserID": {
      "type": "string"
    },
    "Name": {
      "type": "string"
    },
    "Age": {
      "description": "Age in years",
      "type": "integer",
      "minimum": 18
    }
  },
  "required": [
    "UserID",
    "Name"
  ]
}

Crie um modelo para sua API REST

Para criar um modelo no API Gateway, consulte Configurar a validação básica de solicitações no API Gateway.

Associe seu modelo ao método da API

Conclua as etapas a seguir:

1. Abra sua API no console do API Gateway.
2. No painel de navegação, clique em Recursos.
3. Selecione o método de API ao qual você deseja associar o modelo.
4. No painel Execução de método, clique em Solicitação de método.
5. Em Validador de solicitação, selecione Validar corpo. Em seguida, clique no ícone de verificação para salvar sua seleção.
6. Expanda Corpo da solicitação. Em seguida, selecione Adicionar modelo.
7. Em Tipo de conteúdo, insira o tipo de conteúdo do seu modelo. Por exemplo, insira application/json.
8. Em Nome do modelo, selecione o modelo que você criou.
9. Clique no ícone de verificação para salvar suas seleções.

Teste o modelo

Conclua as etapas a seguir:

1. Na lista Recursos da sua API, selecione o método de API ao qual você associou seu modelo.

2. No painel Execução do método, selecione TEST.

3. Em Corpo da solicitação, insira um corpo de solicitação que corresponda ao esquema do modelo que você criou.
   Observação: para testar o modelo de exemplo application/json, use o seguinte exemplo de corpo de solicitação:

   { "UserID": "abc123", "Name": "Ana", "Age": 21}

4. Clique em Testar.

5. Se a resposta do teste for bem-sucedida, o corpo da solicitação retornado corresponderá ao esquema do modelo.

(Opcional) Crie um modelo de mapeamento para o modelo

É possível usar um modelo de mapeamento para modificar as solicitações que são enviadas para o backend integrado da sua API. Para criar um modelo de mapeamento, conclua as seguintes etapas:

1. Na lista Recursos da sua API, selecione o método de API ao qual você associou seu modelo.

2. No painel Execução do método, selecione Solicitação de integração.

3. Expanda Modelos de mapeamento.

4. Em Passagem do corpo da solicitação, clique em Quando não houver modelos definidos (recomendado).

5. Selecione Adicionar modelo de mapeamento.

6. Em Tipo de conteúdo, insira o tipo de conteúdo do seu modelo. Por exemplo, insira application/json.

7. Clique no ícone de verificação para salvar sua seleção.

8. Em Gerar modelo, selecione o modelo que você criou. Por exemplo, o modelo de exemplo application/json aparece da seguinte forma:

   #set($inputRoot = $input.path('$')) { "UserID" : "$inputRoot.UserID", "Name" : "$inputRoot.Name", "Age" : $inputRoot.Age }

9. Modifique o modelo anterior para que ele contenha os valores que você deseja passar para o backend integrado da sua API.

10. Clique em Salvar.

Implante sua API REST para confirmar as alterações

Conclua as etapas a seguir:

1. No painel de navegação, clique em Recursos.
2. Clique em Ações. Em seguida, selecione Implantar API.
3. Em Estágio de implantação, selecione um estágio que já exista ou clique em [New Stage] para criar um estágio.
   Importante: se você criar um novo estágio, deve inserir um nome em Nome do estágio.
4. Selecione Implantar para receber o URL de invocação que você usa para fazer solicitações à sua API implantada.
5. Copie o URL de invocação.

Teste sua API REST

Envie uma solicitação de teste para sua API que usa o método e o tipo de conteúdo associados ao seu modelo. Uma solicitação bem‑sucedida retorna uma resposta 200 OK. Uma solicitação malsucedida retorna um código de status 400.

Para enviar uma solicitação de teste, use uma ferramenta de desenvolvimento de API ou um comando curl. Para obter mais informações sobre chamadas de API REST no API Gateway, consulte Invocar APIs REST no API Gateway. Para obter mais informações sobre o comando curl, consulte o site curl.

Exemplo de comando curl que usa a solicitação do método HTTP POST e testa uma resposta 200 OK

Observação: esse comando de exemplo envia uma solicitação de teste para o modelo application/json de exemplo. O comando retorna uma resposta 200 OK.

curl -X POST <API URL> -H 'Content-Type: application/json' -d '{ "UserID": "abc123", "Name": "Ana", "Age": 21 }'

(Opcional) Exemplo de comando curl que usa a solicitação do método HTTP POST e testa um código de status 400

Observação: o corpo da solicitação neste comando de exemplo não é válido porque não inclui o atributo de modelo obrigatório UserID. O comando retorna um código de status 400.

curl -X POST <API URL> -H 'Content-Type: application/json' -d '{ "Name": "Ana", "Age": 21 }'