Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

2,817 views

Published on

  • Be the first to comment

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

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

×