Edited at

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

More than 3 years have passed since last update.


はじめに

iPhoneやandroid、フロントエンドJavascriptとのAjax通信のためにサーバー側でAPI開発をする時、どんな設計にするのが良いか情報収集していたのですが、その結果をまとめておこうと言う事で書きました。各項目ごとに参考資料もあるので、皆さんがAPI設計をする際の参考としてご活用ください。


どんなバージョニング方法があるか

バージョニング方法は以下の4つがあります。それぞれメリット・デメリットがあるので、その中からサービスの特徴に適した方法を選択します。


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/xxxxx.com/v2/xxxがあるときに、v1フォルダとv2フォルダを作らない。

コピペバージョニングを行ってしまうと、v2を作成時にメンテナンス性が下がります。v2を作成しようとした時点で「あ、これはメンテ出来ないや・・・」という事に気がつく。というより、プログラマとして面白くない設計になってしまう。


限定分岐のバージョニングにしましょう。

例えば5個のapiコントローラがあるときに、1個の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バージョニングに未だ銀の弾丸はないそうです。ぜひ銀の弾丸が見つかるよう、何か追加情報及び意見等あれば気軽に書き込んでもらいたいです。^^