Living Socialが7回に渡りSOA (Service-oriented architecture) についてのブログを書いてますが、今回はAPI設計についてのエントリーです。

「APIはRESTful」と言うだけでなく、社内でガイドラインがオーソライズされるように調整すること。設計にあたっての選択肢及び自由度をしっかり考慮すること。そして一番大事なのは、決めた原則とおりにブレなくインプリすること。

• どのHTTPステータス（success/error）をどのシチュエーションで採用するか。
  • 204もしくは200をPOSTで使うか？PUTで使うか？
  • 4xx番台のコードの一貫性。
• bodyにエラーメッセージを追加するのか。
• 認証はどこで？
  • ヘッダー？もしくはURLパラメータ？
• リソースの階層はどうするか。
  • 忠実にRESTfulとするのか、RPCのようなエンドポイント（/inventory_items/near_city）にするのか？
• ハイパーメディア参照をサポートするのか？シンプルにリソースのIDを示すのか？
  • {'id': 123'} vs {'uri': 'http://some.host.com/api/resource/123'}
• バージョン情報をどこに置くのか？

IDL (Interface Defninition Language) は、

• スキーマでAPIを定義。
• 事前もビルドステップ（rakeタスク等）、もしくはエンドポイントのIDL定義をクライアントが利用する段階で、クライアントライブラリ/gems/ (場合によっては) サーバサイドのスタブを生成してくれる。
• 開発言語をまたいで利用できる。
• ドキュメントを自動生成してくれる。

Living Socialでは、APIの作成/管理にSwaggerを使っている。

また、Herokuは、もろもろ細かく規定したAPI設計ポリシーをGithub上で公開しています。

#livingsocial #heroku #api