Heroku HTTP API Design Guide
- 1. HTTP API Design Guide HerokuのAPIデザインガイド Ayumu Aizawa Dev. Marketing Manager / Solutions Architect Heroku Inc. 27th Mar,2015
- 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