REST API のデータモデル - Amazon API Gateway
より複雑なモデルの作成出力データモデルを使用する次のステップ

REST API のデータモデル

API Gateway では、モデルはペイロードのデータ構造を定義します。API Gateway では、JSON スキーマのドラフト 4 を使用してモデルを定義します。次の JSON オブジェクトは、PetStore の例のサンプルデータです。

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

データには、ペットの id、type、price が含まれています。このデータのモデルにより、以下のことが可能になります。

  • 基本的なリクエストの検証を使用する。

  • データ変換用のマッピングテンプレートを作成する。

  • SDK を生成するときに、ユーザー定義データ型 (UDT) を作成する。

PetStore API の JSON データモデルの例。

このモデルの内容は以下のとおりです。

  1. $schema オブジェクトは、有効な JSON スキーマのバージョン識別子を表します。このスキーマは JSON スキーマのドラフト v4 です。

  2. title オブジェクトは、人間が読めるモデルの識別子です。このタイトルは PetStoreModel です。

  3. required 検証キーワードには、基本的なリクエストの検証用の type と price が必要です。

  4. モデルの properties は、id、type、price です。各オブジェクトには、モデルに記述されているプロパティがあります。

  5. オブジェクト type は、値として dog、cat、fish のいずれかのみを持つことができます。

  6. オブジェクト price は数値で、minimum が 25、maximum が 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 }

このモデルの内容は以下のとおりです。

  1. 2 行目で、$schema オブジェクトは有効な JSON スキーマのバージョン識別子を表します。このスキーマは JSON スキーマのドラフト v4 です。

  2. 3 行目で、title オブジェクトは、人間が読めるモデルの識別子です。このタイトルは PetStoreModel です。

  3. 5 行目で、required 検証キーワードには、基本的なリクエストの検証用の type と price が必要です。

  4. 6～17 行目で、モデルの properties は id、type、price です。各オブジェクトには、モデルに記述されているプロパティがあります。

  5. 12 行目で、オブジェクト type は値として dog、cat、fish のいずれかのみを持つことができます。

  6. 14～17 行目で、オブジェクト price は数値で、minimum が 25、maximum が 500 に制限されます。

より複雑なモデルの作成

$ref プリミティブを使用すると、より長いモデルの再利用可能な定義を作成できます。例えば、price オブジェクトを記述する definitions セクションで、Price という定義を作成できます。$ref の値は 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
            }
      }
}

外部モデルファイルで定義された別のモデルスキーマを参照することもできます。$ref プロパティの値をモデルの場所に設定します。次の例では、Price モデルは API a1234 の PetStorePrice モデルに定義されています。

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

より長いモデルは 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"
    }
  }
}

出力データモデルを使用する

データを変換する場合、統合レスポンスでペイロードモデルを定義できます。ペイロードモデルは SDK を生成するときに使用できます。Java、Objective-C、Swift などの厳密に型指定された言語では、オブジェクトはユーザー定義データ型 (UDT) に対応します。SDK の生成時にデータモデルで UDT を指定すると、API Gateway は UDT を作成します。データ変換の詳細については、「REST API のマッピングテンプレート」を参照してください。

以下は、統合レスポンスからの出力データの例です。

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

次の例は、出力データを記述するペイロードモデルです。

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

このモデルでは、SDK を呼び出し、PetStoreOutputModel[i].description プロパティと PetStoreOutputModel[i].askingPrice プロパティを読み取ることで、description と askingPrice のプロパティ値を取得できます。モデルが指定されていない場合、API Gateway は空のモデルを使用してデフォルト UDT を作成します。

次のステップ