JSON Schema で
Web API のスキマを埋めよう
海老原昂輔 (@co3k)
クライアント実装サーバ実装
仕様
Web API にありがちなこと
API	 ドキュメント
リクエストレスポンス
ぶっちゃけAPI	 の追加時く
らいしか更新していない
なぜかドキュメントにない属性が
含まれている
手が滑ってドキュメントと若干違う形式の
属性を含めちゃったけどなんとなく通った
クライアント実装サーバ実装
仕様
いまは API Blueprint で頑張ってる

(http://apiblueprint.org/)
API	 ドキュメント
リクエストレスポンス
Markdown	 の

スーパーセット

(ツラい)
API	 Blueprint

(YAML	 表現)
generate
mockvalidate
あんまり嬉しく
ない
なんか別に	  JSON	 
Schema	 書かない
といけない
クライアント実装サーバ実装
仕様
今日話したいこと
JSON	 Schema
API	 ドキュメント
リクエストレスポンス
generate
validatevalidate
API	 仕様の	 DSL
ドキュメントが仕様に追従
していることを保証
入力処理の実装が仕様に
追従していることを保証
出力処理の実装が仕様に
追従していることを保証
クライアント実装サーバ実装
仕様
(まだ) 無理だった
JSON	 Schema
API	 ドキュメント
リクエストレスポンス
generate
API	 仕様の	 DSL
ドキュメントが仕様に追従
していることを保証
JSON Schema
• リソースや attribute、 JSON を用いた API について表現
することができるフォーマット (http://json-schema.org/
documentation.html)
• JSON Schema Core
• JSON Schema Validation
• JSON Hyper-Schema
JSON Schema
$ curl https://api.heroku.com/
schema -H "Accept:
application/vnd.heroku+json;
version=3"
Validation (予定)
• JSON Schema 仕様に基づく validate 用ライブラリは言
語問わず腐るほどあるはずなのでそれを使えばよい
• 入力も JSON Schema でバリデーションするようにすれば
(ある程度の) 入力値検証は自分で書かなくても済む
• 出力は JSON Schema のバリデーションに通るかどうかだ
け確認すれば (ある程度の) テストは自分で書かなくても
済む
Documentation
• prmd で生成するのがオススメ
• Heroku の API ドキュメント用に作られた
• JSON Hyper-Schema から GitHub Markdown を出力し
てくれる
• erb 形式のテンプレートで出力をカスタマイズ可能
• 海老原も contribute している
Documentation
https://github.com/interagent/prmd
実例
https://devcenter.heroku.com/
articles/platform-api-reference
Heroku Interagent
https://github.com/interagent/
interagent/committee
• Rack middleware to validate responses according
to JSON schema



JSON スキーマに基づくレスポンスのバリデーションをする
Rack ミドルウェア
interagent/schematic
• Generate Go client code for HTTP APIs described by
JSON Hyper-Schemas.



JSON Hyper-Schema によって記述された HTTP API の
Go クライアントを生成する
interagent/http-api-design
• HTTP API design guide extracted from work on the
Heroku Platform API



Heroku Platform API の成果物から派生した HTTP API の
設計ガイド
• 昨日の 25 時になぜか和訳をはじめた https://
github.com/co3k/http-api-design/tree/translate-
japanese
interagent/heroics
!
!
• Ruby HTTP client for APIs represented with JSON
schema



JSON スキーマによって表現された API のための Ruby
HTTP クライアント
クライアント実装サーバ実装
仕様
まとめ
JSON	 Schema
API	 ドキュメント
リクエストレスポンス
generate
validatevalidate
API	 仕様の	 DSL
ドキュメントが仕様に追従
していることを保証
入力処理の実装が仕様に
追従していることを保証
出力処理の実装が仕様に
追従していることを保証
Question?

JSON Schema で Web API のスキマを埋めよう