API Meetup Mar 27, 2015

What's hot

Similar to Heroku HTTP API Design Guide

More from Ayumu Aizawa

Heroku HTTP API Design Guide

• 1.
  HTTP API DesignGuideHerokuのAPIデザインガイド
Ayumu Aizawa
Dev. Marketing Manager / Solutions Architect
Heroku Inc.27th Mar,2015
• 2.
  Designing APIAPIを設計することは世界を創造することオレオレワールドに陥りやすい
ぼくのかんがえたさいきょうの⃝⃝
• 3.
  Heroku’s HTTP APIDesign Guide
• 4.
  Heroku’s HTTP APIDesign GuideHerokuのAPIデザインから得た知見をまとめた
API設計のガイドラインdevcenter.heroku.com/categories/platform-apigithub.com/interagent/http-api-designHeroku Platform API
• 5.
  Separate ConcernsAPIはユーザの関心ごとに応じて適切に分割する• 必ずしも内部のリソース構造と同じではない•ユーザ対してサービスの単位をどうみせるか？• アプリケーション、アカウント、ビルド、Dyno、ドメイン
….
• 6.
  Require Secure ConnectionAPIの呼び出しは例外なくTLSなどの安全な通信のみ
に応答するように実装する•何をセキュアにして何をセキュアにしないか？ではなく
全てをセキュアに保つ• APIが提供する機能がセキュリティ脆弱性があった場合の影響を
軽減
• 7.
  Use consistent pathformatエンドポイントには一貫したフォーマットを利用する• 基本的なリソースの操作に関しては、操作をパスに含める
必要はないが、必要な場合には /actions の下に定義/runs/{run_id}/actions/stop
• 8.
  Provide Request-Ids forIntrospectionリソースにはグローバルで一意になるIDを付与する• リソースのトレーサビリティ• 同じIDは常に同じリソースを返す
• 9.
  Divide Large ResponsesAcrossRequests with Rangesレスポンスが大きくなる時には”Range”でデータを分割する• リクエストヘッダーで範囲を指定• 必要であればソート順なども指定
• 10.
  Return appropriate statuscodesクライアントからのリクエストに対して適切な
HTTPステータスコードで応答する• 200：GETリクエストの成功、
DELETE/PATCH/PUTによる
情報の更新が完了• 201：POSTリスエストによる
情報の作成が完了• 202：POST/DELETE/PATCH/PUTを受付けた更新は非同期で
実行される• 206：GETリスエストが正常に
受付けられたが一部の情報のみ
返す
• 11.
  Provide executable example実行可能な利用例を提供する•ユーザが実際に端末から（手で）実行可能な利用例を提供
• 12.
  Provide machine-readable JSONschema
Provide human-readable docsプログラムで処理しやすいJSONスキーマを提供する
人間が読みやすいドキュメントを提供する
• 13.
  PrmdJSONスキーマの作成、検証、ドキュメント生成prmd init :JSONスキーマの雛形を作成prmd verify: JSONスキーマの検証prmd doc: ドキュメントの生成
• 14.
  Heroku’s HTTP APIDesign Guideくわしくはこちらを御覧くださいdevcenter.heroku.com/categories/platform-apigithub.com/interagent/http-api-designHeroku Platform API
• 15.
  Thank youheroku.com