Transcript

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