api開発に失敗しないための情報収集まとめ

6878 ワード
versioning api オーケストレーション層 api テキストリンク

はじめに

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

例

(参考資料)
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
Grails document

Web APIは HTML Webアプリと同じように設計する

Web APIは特別なものではなく、ただ表現フォーマットが違うだけ。同じ扱いにするべきもの。

（参考資料)
webを支える技術（本)

API開発者Tips

  • クライアントが増えるとAPIが増えるという悩みにぶつかる。
  • LSUEという言葉がある。
  • オーケストレーション層をつくるのが流行りだしている。 (参考資料) TNW Blog
  • サーバー側ではなく、クライアント側がAPIを開発するという考えがある。mBaaSのparse.comが似た形を実現。

その他参考資料

最後に

もう少し整理してから投稿したかったのですが、途中で力尽きました（笑）。
今後も少しずつ改訂していって資料をまとめていく予定です。

最後の最後に

APIバージョニングに未だ銀の弾丸はないそうです。ぜひ銀の弾丸が見つかるよう、何か追加情報及び意見等あれば気軽に書き込んでもらいたいです。＾＾