json schema で web api のスキマを埋めよう
TRANSCRIPT
![Page 1: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/1.jpg)
JSON Schema で Web API のスキマを埋めよう
海老原昂輔 (@co3k)
![Page 2: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/2.jpg)
クライアント実装サーバ実装
仕様
Web API にありがちなこと
API ドキュメント
リクエストレスポンス
ぶっちゃけAPI の追加時くらいしか更新していない
なぜかドキュメントにない属性が含まれている
手が滑ってドキュメントと若干違う形式の属性を含めちゃったけどなんとなく通った
![Page 3: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/3.jpg)
クライアント実装サーバ実装
仕様
いまは API Blueprint で頑張ってる(http://apiblueprint.org/)
API ドキュメント
リクエストレスポンス
Markdown のスーパーセット (ツラい)
API Blueprint (YAML 表現)
generate
mockvalidate
あんまり嬉しくない
なんか別に JSON Schema 書かないといけない
![Page 4: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/4.jpg)
クライアント実装サーバ実装
仕様
今日話したいこと
JSON Schema
API ドキュメント
リクエストレスポンス
generate
validatevalidate
API 仕様の DSL
ドキュメントが仕様に追従していることを保証
入力処理の実装が仕様に追従していることを保証
出力処理の実装が仕様に追従していることを保証
![Page 5: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/5.jpg)
クライアント実装サーバ実装
仕様
(まだ) 無理だった
JSON Schema
API ドキュメント
リクエストレスポンス
generate
API 仕様の DSL
ドキュメントが仕様に追従していることを保証
![Page 6: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/6.jpg)
JSON Schema
•リソースや attribute、 JSON を用いた API について表現することができるフォーマット (http://json-schema.org/documentation.html)
• JSON Schema Core
• JSON Schema Validation
• JSON Hyper-Schema
![Page 7: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/7.jpg)
JSON Schema
$ curl https://api.heroku.com/schema -H "Accept: application/vnd.heroku+json; version=3"
![Page 8: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/8.jpg)
Validation (予定)
• JSON Schema 仕様に基づく validate 用ライブラリは言語問わず腐るほどあるはずなのでそれを使えばよい
•入力も JSON Schema でバリデーションするようにすれば (ある程度の) 入力値検証は自分で書かなくても済む
•出力は JSON Schema のバリデーションに通るかどうかだけ確認すれば (ある程度の) テストは自分で書かなくても済む
![Page 9: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/9.jpg)
Documentation
•prmd で生成するのがオススメ
•Heroku の API ドキュメント用に作られた
• JSON Hyper-Schema から GitHub Markdown を出力してくれる
•erb 形式のテンプレートで出力をカスタマイズ可能
•海老原も contribute している
![Page 11: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/11.jpg)
実例
https://devcenter.heroku.com/articles/platform-api-reference
![Page 13: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/13.jpg)
interagent/committee
•Rack middleware to validate responses according to JSON schemaJSON スキーマに基づくレスポンスのバリデーションをする Rack ミドルウェア
![Page 14: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/14.jpg)
interagent/schematic
•Generate Go client code for HTTP APIs described by JSON Hyper-Schemas.JSON Hyper-Schema によって記述された HTTP API の Go クライアントを生成する
![Page 15: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/15.jpg)
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
![Page 16: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/16.jpg)
interagent/heroics
!
!
•Ruby HTTP client for APIs represented with JSON schemaJSON スキーマによって表現された API のための Ruby HTTP クライアント
![Page 17: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/17.jpg)
クライアント実装サーバ実装
仕様
まとめ
JSON Schema
API ドキュメント
リクエストレスポンス
generate
validatevalidate
API 仕様の DSL
ドキュメントが仕様に追従していることを保証
入力処理の実装が仕様に追従していることを保証
出力処理の実装が仕様に追従していることを保証
![Page 18: JSON Schema で Web API のスキマを埋めよう](https://reader031.vdocuments.net/reader031/viewer/2022013111/55acced21a28ab0b2c8b47d4/html5/thumbnails/18.jpg)
Question?