こんにちは、開発チームのmzpです。MisocaのiPhoneアプリがリリースできて、ほっとしています。
今回は、このiPhoneアプリ用のためにつくったAPIについて書きたいと思います。
提供するAPIの種類
MisocaではすでにAPIv1と呼ばれるRESTful APIの提供を行なっています。
しかし、iPhoneアプリ開発では、以下のような理由から、APIv1を拡張するのではなく新規にAPIを作成することにしました。
このように特定のアプリケーション向けのAPIのことをSSKD (small set of known developers)*1 と呼ぶそうです。
なお、新規のAPIのことをAPIv2と呼んでいます。「別にバージョンあがったわけじゃないのに、v2と呼ぶのは違和感ある」との意見もあったのですが、「vはversionのvではなく、variantのvだ」ということで決着(?)しています。
実装の方針
現状のWebUIと新規のAPIv2でコードの重複を避けるために、コントローラとモデルの間に中間層を設け、そこで共通の処理を行なうようにしています。
MisocaではコードをThe Clean Architecture*2に沿って整理しているで、この中間層をUsecase objectと呼んでいます。
設計時に書いた概要図:
検討したライブラリ
APIv2実装にあたって利用を検討したライブラリについて紹介していきます。
CRUDの生成
APIの実装を簡略するためにGarageの利用を検討しました。試しにいくつかのAPIを実装してみたところ、以下のような感想を持ちました。
- どの権限に足して、どの属性を公開していいかをモデル側に記述できる
- 便利ではあるが、モデルがgarage依存になってしまう
- doorkeeperのscopeごとに何ができるかを一箇所で書ける
- CRUDは、ほぼ自動生成できるので楽
今回のAPIv2開発において「iPhoneアプリからしか使わないためscopeごとの権限制御は不要」「単純なCRUDはそれほど数がない」「APIv2だけの都合でモデルを変更したくない」といった理由から、利用は見送りました。 設計時に書いた文書には「気合でがんばる。気合があればなんとかなる」と書いてあります。
ドキュメントの生成
iPhoneアプリの開発担当者に渡すドキュメントを自動生成するために、以下の2つのライブラリを検討しました。
- API Blueprint: 一個のドキュメントから、mockサーバや、ドキュメントとかを生成できる
- rspec_api-blueprintを使えば、specからドキュメントを生成できる。
- autodoc: specからドキュメントを生成する
- パラメータの説明も書きたい場合は、weak_parametersと併用する必要がある
両方を比較した結果、以下の理由でautodocを利用することにしました。
- autodocよりAPI Blueprintのほうが多機能
- ただrspec_api_blueprintよりautodocのほうが機能が豊富
- パラメータの説明やAPIの説明も書ける
- 出力パスや出力形式の設定もできる
ただ、いくつかの機能が不足していたため、いくつかPull requestsを送りました。
生成されたドキュメントの例:
ページネーション
いくつかのAPIでページネーションが必要だったため、RFC 5988 - Web Linkingを実現できるapi-paginationを採用しました。これは、Httpヘッダに「次のページ」と「最後のページ」へのリンクを埋め込む形式です。
Link: <http://localhost:3000/movies?page=1>; rel="first", <http://localhost:3000/movies?page=173>; rel="last", <http://localhost:3000/movies?page=6>; rel="next", <http://localhost:3000/movies?page=4>; rel="prev"
GithubのAPIでも採用されているので無難かと思ったのですが、iPhoneアプリの実装が楽になるようなことはなかったようです。
その他所感
- WebUIとAPIv2の2系統があると、どこまでがAPI固有処理なのかの判断がしやすくてよい
- 設計時に上記のような文書をQiita:teamにまとめておいてよかった
- MisocaのiPhoneアプリをぜひご利用ください!!
