API設計のポイント

https://techblog.livingsocial.com/blog/2014/06/26/soa-series-part-3-documenting-and-generating-your-apis/

1 comment | 0 points | by WazanovaNews 2年以上前 edited


Jshiike 2年以上前 edited | ▲upvoteする | link

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

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

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

IDL (Interface Defninition Language) は、

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

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

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

#livingsocial #heroku #api

Back