API Meetup Mar 27, 2015

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