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

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

## どんなバージョニング方法があるか
バージョニング方法は以下の４つがあります。それぞれメリット・デメリットがあるので、その中からサービスの特徴に適した方法を選択します。
#### 1. http headerをカスタムしてapi-versionを書き込む
ex) x-api-version: 1

オンライン・オフラインの区別がほとんどないサービスに有効。OAuthベースシステムのサービスとも親和性が高い。api-versionの指定がヘッダーにない場合は最新を使うのが一般的。
##### 使用例
* [facebook graph](https://developers.facebook.com/docs/graph-api/using-graph-api/v2.1)
 
#### 2. http content-typeに含める
ex) application/com.xxxx.v2+json
##### 使用例
* [github](https://developer.github.com/v3/)

#### 3. パラメータ形式
ex) /api/xxxx?api_version=1
#### 4. ルーティングに含める
ex) /api/v1/xxxx, /api/v2/xxxx

##### 例
* [foursquare](https://developer.foursquare.com/docs/)
* [linkedin](https://developer.linkedin.com/apis)
* [qiita](https://qiita.com/docs)
* [foursquare](https://developer.foursquare.com/docs/)
* [はてなブックマーク](http://developer.hatena.ne.jp/ja/documents/bookmark/apis/rest)
* [chatwork](http://developer.chatwork.com/ja/endpoints.html)
* [hipchat](https://www.hipchat.com/docs/apiv2/auth)
* [twilio (日付バージョニング)](https://jp.twilio.com/docs/api/rest/request)
* [pivotal tracker](http://www.pivotaltracker.com/help/api#Special_Endpoint_Usage)
* [trello](https://trello.com/docs/gettingstarted/index.html)

(参考資料)
[api ux](http://apiux.com/2013/05/14/api-versioning/)
[O'REILLY community](http://broadcast.oreilly.com/2011/10/api-versioning.html)
[github developer blog](https://developer.github.com/v3/media/)




## バージョンごとにファイルをつくらない
``xx.com/v1/xxx``と``xx.com/v2/xxx``があるときに、v1フォルダとv2フォルダを作らない。
**コピペバージョニングを行ってしまうと、v2を作成時にメンテナンス性が下がります。**v2を作成しようとした時点で「あ、これはメンテ出来ないや・・・」という事に気がつく。というより、プログラマとして面白くない設計になってしまう。
#### 限定分岐のバージョニングにしましょう。
例えば５個のapiコントローラがあるときに、１個のapiコントローラだけ内容を変更する場合は、例えばそのコントローラ内にバージョン分岐の処理を加えるようにしましょう。

#### リソースとコントローラは別だという事を意識しましょう。
リソースとコントローラをつなげる役割を担うのはRoutingです。RubyOnRailsだとActiveResourceです。ActiveResourceが何のためにあるのかを忘れないようにしましょう。

(参考資料）
[APIのバージョニングは限局分岐でやるのが良い](http://kenn.hatenablog.com/entry/2014/03/06/105249)


## 外部デベロッパー向けAPIと内部デベロッパー向けAPIを別APIにする

(参考資料)
[rebuild.fm/35](http://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](http://www.slideshare.net/tkawa1/rubykaigi2014-hypermedia-the-missing-element)
[Spring article](http://spring.io/understanding/HATEOAS)
[REST: From GET to HATEOAS](Hypwemedia The Missing Element)
[Grails document](http://grails.org/doc/2.3.x/guide/webServices.html#hypermedia)

## Web APIは HTML Webアプリと同じように設計する
Web APIは特別なものではなく、ただ表現フォーマットが違うだけ。同じ扱いにするべきもの。

（参考資料)
[webを支える技術（本)](http://www.amazon.co.jp/Web%E3%82%92%E6%94%AF%E3%81%88%E3%82%8B%E6%8A%80%E8%A1%93-HTTP%E3%80%81URI%E3%80%81HTML%E3%80%81%E3%81%9D%E3%81%97%E3%81%A6REST-WEB-PRESS-plus/dp/4774142042)

## API開発者Tips
* クライアントが増えるとAPIが増えるという悩みにぶつかる。
* LSUEという言葉がある。
* オーケストレーション層をつくるのが流行りだしている。
(参考資料)
[TNW Blog](http://thenextweb.com/dd/2013/12/17/future-api-design-orchestration-layer/)
* サーバー側ではなく、クライアント側がAPIを開発するという考えがある。mBaaSのparse.comが似た形を実現。


## その他参考資料
* [失敗から学ぶAPI設計](http://www.slideshare.net/yusukey/api-ccch4-jjug-jjugccc-jjug-ccc-2013-spring)
* [cookpadのマイクロサービス設計](http://techlife.cookpad.com/entry/2014/09/08/093000)
* [microservicesに分割する際に注意するべき5つのこと(qiita記事)](http://qiita.com/hirokidaichi/items/bf81f1f6f7ca3d694aae)
* [web+db-press v82](http://www.amazon.co.jp/WEB-DB-PRESS-Vol-82-%E5%B1%B1%E5%8F%A3/dp/4774166278)

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

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