スキップしてメイン コンテンツに移動

API Request Validationのスキーマとフォーマット

Topics:

API Gatewayを使ってる。
そのとき、たとえば処理を後続のLambdaなどに繋ぐような構成だとする。
この場合に、できることなら、想定しているフォーマットを満たさないリクエストは後続につなぐまでもなくAPI Gatewayで弾きたい。
それを実現してくれるのがAPI Request Validationの機能。

ただ、ドキュメントを見てもJSON Schemaの仕様のDraft v4に従っている、以上でも以下でもなくそれしか情報がなく困惑していたのでメモ。
結果的には、一部の書き方が違うだけで、基本的にOpenAPIで定義できるようなものはほとんど使えると考えて差し支えなさそう。

下記はAPI Gatewayに定義したモデルの一例。

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "object",
	"properties": {
		"status": {
			"type": "string",
			"minLength": 1,
			"maxLength": 16
		},
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 255
		},
		"id": {
			"type": "string",
			"format": "uuid"
		},
		"custom_attributes": {
			"type": "string",
			"minLength": 2,
			"maxLength": 65536,
			"pattern": "\\{[\\s\\S]*\\}"
		}
	},
	"required": ["id"]
}

JSON Schema draft v4のリンクはこちら。
- draft-zyp-json-schema-04 - JSON Schema: core definitions and terminology https://tools.ietf.org/html/draft-zyp-json-schema-04
- draft-fge-json-schema-validation-00 - JSON Schema: interactive and non interactive validation https://tools.ietf.org/html/draft-fge-json-schema-validation-00

で、罠がこれ。

Integrate a Model with an API Gateway API

今となってはわかったので良いのだけど、このページのリンクの記載からはJSON Schema v4のCoreのページに飛ばされ、それがサポートしている仕様だとわかる。
しかし、JSON SchemaのSpecについて書いてあるページを見ると見落としがあることがわかる。

The specification is split into two parts, Core and Validation. We also publish the Relative JSON Pointers spec although it’s not currently used by Core or Validation in any significant way.

つまり、SpecはCoreとValidationで1つ。しかしリンクされている先だけを素直に見てしまい、おや？どうもサポートしているのはかなり限定的な内容で、例えばminLengthのようなものはないんだな、と誤解してしまう。

改めて生成されているJSON Schemaのファイルの中にあるschemaプロパティのリンク先から手に入るJSONファイルを見ると、Coreの内容はdefinition以下を中心に、Validationの内容はpropertiesの中を中心に記載されていることがわかる。

http://json-schema.org/draft-04/schema#


というわけで、ここまでわかればCoreとValidation、2つの内容を見て実装を進めれば、期待するバリデーションができる、ということがわかる。

AWSのProfessional Serviceの人もなぜ（リンクされているCoreのページを見て）ここに書かれていないものがAPI Gatewayで実際に動いているのかは社内文書を見てもよくわからなかった旨の回答をしている。わからない人は書いてあることだけに従う傾向があるから（頼れるものはないのだから当たり前だね）、公開ガイドでミスリードをすることは避けてほしいなと思ったし、自分に対する戒めにもなった。

無事動くと、今までは全てバックエンドでの検証に任せていたので、結構気持ちいい。