😽

API Gateway　REST API のテンプレート変換

に公開
AWS
Amazon API Gateway
tech

はじめに

AWS API Gateway は、クライアントとバックエンドの間に立ってリクエストやレスポンスを仲介する「フロントドア」のようなサービスです。モバイルアプリやフロントエンドからのリクエストを受け取り、バックエンドの Lambda、DynamoDB、HTTP エンドポイントなどに橋渡しをしてくれます。

ただし、クライアントとバックエンドは必ずしも同じ形式でデータをやり取りしているわけではありません。そこで登場するのが マッピングテンプレートです。この記事では、API Gateway のリクエスト／レスポンス処理の流れと、マッピングテンプレートの役割について整理します。

API Gateway のリクエストライフサイクル

API Gateway では、リクエストとレスポンスの間に以下の概念があります。

メソッドリクエスト (Method Request)
クライアントが API に送るリクエスト。

統合リクエスト (Integration Request)
バックエンドに渡される前のデータ。マッピングテンプレートを使って変換できる。

統合レスポンス (Integration Response)
バックエンドから返ってきたデータ。マッピングテンプレートで整形できる。

メソッドレスポンス (Method Response)
クライアントに返される最終的なレスポンス。

つまり、API Gateway はクライアントとバックエンドの間で「翻訳機」のように動作します。

マッピングテンプレート　とは

API Gateway の マッピングテンプレート は、VTL (Velocity Template Language) を使って、統合リクエスト (Integration Request)、統合レスポンス (Integration Response)のデータを 変換・整形 するための仕組みです。

また、VTL は Velocity Template Language（ベロシティ・テンプレート・ランゲージ）の略です。

これは Apache Velocity というテンプレートエンジンの一部で、API Gateway の 「統合リクエスト」や「統合レスポンス」マッピングテンプレート で使われています。

マッピングテンプレートを使用することで、以下のメリットがあります。


メリット

  • クライアントとバックエンドのフォーマットのズレを吸収できる
  • DynamoDB などと直接統合する場合に必須
  • レスポンスをシンプルにしてクライアントに返せる

具体例：ペット API

リクエスト変換
例えば、ユーザーがペット情報を送信する API があるとします。

クライアントが送るデータ

{
  "id": 1,
  "type": "dog",
  "Age": 11
}

しかしバックエンドは、次の形式で受け取りたいとします。

{
  "dogId": "dog_1",
  "Age": 11
}

ここでマッピングテンプレートを使います。

#set($inputRoot = $input.path('$'))
{
  "dogId": "dog_"$inputRoot.id,
  "Age": $inputRoot.Age
}

結果、バックエンドには次のデータが渡されます。

{
  "dogId": "dog_1",
  "Age": 11
}


レスポンス変換

バックエンドから次のようなレスポンスが返ってきたとします。

{
  "dogId": "dog_1",
  "adoptionFee": 19.95
}

クライアントにはシンプルに料金だけ返したい場合、次のテンプレートを設定します。

#set($inputRoot = $input.path('$'))
{
  "adoptionFee": $inputRoot.adoptionFee
}

クライアントが受け取るデータは、下記のようになります。

{
  "adoptionFee": 19.95
}


まとめ

API Gateway はクライアントとバックエンドをつなぐ「翻訳機」です。また、統合リクエスト／統合レスポンスでマッピングテンプレートを使い、データを整形することができます。

さらに、マッピングテンプレートは VTL で記述し、DynamoDB 直結やレスポンスの簡略化に便利です。

最近は Lambda プロキシ統合を使ってバックエンドで変換するケースも増えていますが、Lambda を使わない場合や、レスポンスを軽量化したいときにはマッピングテンプレートが非常に有効です。

参考

https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/models-mappings.html

Discussion