Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
JSON Schema で Web API のスキマを埋めよう
Search
Kousuke Ebihara
May 15, 2014
9
4.6k
JSON Schema で Web API のスキマを埋めよう
Kousuke Ebihara
May 15, 2014
Tweet
Share
More Decks by Kousuke Ebihara
See All by Kousuke Ebihara
YAPC::Asia Tokyo 行ってきた (橙で地獄谷も食べた)
co3k
0
1.4k
戦姫絶唱エンジニア (#pixivoyage)
co3k
0
190
VOYAGE GROUP 2014/06 セキュリティ勉強会 (エンジニア向け / 公開版)
co3k
1
800
Featured
See All Featured
GitHub's CSS Performance
jonrohan
1031
460k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
15
1.5k
Six Lessons from altMBA
skipperchong
28
3.8k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
667
120k
Connecting the Dots Between Site Speed, User Experience & Your Business [WebExpo 2025]
tammyeverts
5
210
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
34
5.9k
Done Done
chrislema
184
16k
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
PRO
181
53k
Code Reviewing Like a Champion
maltzj
524
40k
BBQ
matthewcrist
89
9.7k
How STYLIGHT went responsive
nonsquared
100
5.6k
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
Transcript
JSON Schema で Web API のスキマを埋めよう 海老原昂輔 (@co3k)
クライアント実装 サーバ実装 仕様 Web API にありがちなこと API ドキュメント リクエスト レスポンス
ぶっちゃけAPI の追加時く らいしか更新していない なぜかドキュメントにない属性が 含まれている 手が滑ってドキュメントと若干違う形式の 属性を含めちゃったけどなんとなく通った
クライアント実装 サーバ実装 仕様 いまは API Blueprint で頑張ってる (http://apiblueprint.org/) API ドキュメント
リクエスト レスポンス Markdown の スーパーセット (ツラい) API Blueprint (YAML 表現) generate mock validate あんまり嬉しく ない なんか別に JSON Schema 書かない といけない
クライアント実装 サーバ実装 仕様 今日話したいこと JSON Schema API ドキュメント リクエスト レスポンス
generate validate validate 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 validate validate API 仕様の DSL ドキュメントが仕様に追従 していることを保証 入力処理の実装が仕様に 追従していることを保証 出力処理の実装が仕様に 追従していることを保証
Question?