はじめに
iPhoneやandroid、フロントエンドJavascriptとのAjax通信のためにサーバー側でAPI開発をする時、どんな設計にするのが良いか情報収集していたのですが、その結果をまとめておこうと言う事で書きました。各項目ごとに参考資料もあるので、皆さんがAPI設計をする際の参考としてご活用ください。
どんなバージョニング方法があるか
バージョニング方法は以下の４つがあります。それぞれメリット・デメリットがあるので、その中からサービスの特徴に適した方法を選択します。
1. http headerをカスタムしてapi-versionを書き込む
ex) x-api-version: 1
オンライン・オフラインの区別がほとんどないサービスに有効。OAuthベースシステムのサービスとも親和性が高い。api-versionの指定がヘッダーにない場合は最新を使うのが一般的。
使用例
2. http content-typeに含める
ex) application/com.xxxx.v2+json
使用例
3. パラメータ形式
ex) /api/xxxx?api_version=1
4. ルーティングに含める
ex) /api/v1/xxxx, /api/v2/xxxx
例
- foursquare
- qiita
- foursquare
- はてなブックマーク
- chatwork
- hipchat
- twilio (日付バージョニング)
- pivotal tracker
- trello
(参考資料)
api ux
O'REILLY community
github developer blog
バージョンごとにファイルをつくらない
xx.com/v1/xxxとxx.com/v2/xxxがあるときに、v1フォルダとv2フォルダを作らない。
**コピペバージョニングを行ってしまうと、v2を作成時にメンテナンス性が下がります。**v2を作成しようとした時点で「あ、これはメンテ出来ないや・・・」という事に気がつく。というより、プログラマとして面白くない設計になってしまう。
限定分岐のバージョニングにしましょう。
例えば５個のapiコントローラがあるときに、１個のapiコントローラだけ内容を変更する場合は、例えばそのコントローラ内にバージョン分岐の処理を加えるようにしましょう。
リソースとコントローラは別だという事を意識しましょう。
リソースとコントローラをつなげる役割を担うのはRoutingです。RubyOnRailsだとActiveResourceです。ActiveResourceが何のためにあるのかを忘れないようにしましょう。
(参考資料）
APIのバージョニングは限局分岐でやるのが良い
外部デベロッパー向けAPIと内部デベロッパー向けAPIを別APIにする
(参考資料)
rebuild.fm/35
HATEOAS形式で返す
HATEOASとは？
Hypermedia As The Engine Of Application Stateの略。
RESTfulパターンを拡張したアーキテクチャパターン。
そもそも、Hypermediaって？
クライアントが次にする事をリンクから選べるようにする事。
Hypermedia : Hyper(最高の)+ media(情報提供媒体)
具体的な形式
- リンクでリソース間のrelationを表す事
- リンクで次に可能なアクションを表す
xxx:{
name: yyy,
link: {
rel: "self",
url: "xxx.com/xxx/1"
}
}
(参考資料）
Hypermedia The Missing Element
Spring article
[REST: From GET to HATEOAS](Hypwemedia The Missing Element)
Grails document
Web APIは HTML Webアプリと同じように設計する
Web APIは特別なものではなく、ただ表現フォーマットが違うだけ。同じ扱いにするべきもの。
（参考資料)
webを支える技術（本)
API開発者Tips
- クライアントが増えるとAPIが増えるという悩みにぶつかる。
- LSUEという言葉がある。
- オーケストレーション層をつくるのが流行りだしている。
(参考資料)
TNW Blog - サーバー側ではなく、クライアント側がAPIを開発するという考えがある。mBaaSのparse.comが似た形を実現。
その他参考資料
##最後に
もう少し整理してから投稿したかったのですが、途中で力尽きました（笑）。
今後も少しずつ改訂していって資料をまとめていく予定です。
##最後の最後に
APIバージョニングに未だ銀の弾丸はないそうです。ぜひ銀の弾丸が見つかるよう、何か追加情報及び意見等あれば気軽に書き込んでもらいたいです。＾＾