ネイティブアプリ向け API サーバを作った時の経験談

2014/12/12
nulltask @ いいオフィス

自己紹介

みなさん API サーバ書いてますか？

API サーバとは

クライアントに対して XML や JSON などのフォーマットでレスポンスを返すサーバのこと。

Web API で想定されるクライアント
- Web アプリケーション
- ネイティブアプリケーション

今日はネイティブアプリケーションでの実装時の注意を紹介します。

ウェブアプリとネイティブアプリの違い

デプロイメント

Web App: 即時
Native App: 即時ではない

すぐに変更を反映できない。つらい。

クライアント側のバージョンアップ

Web App: キャンセル不可
Native App: キャンセル可能

常に最新版を使ってもらえるわけではない。つらい。

レスポンスの変更

Web App: 変更に対して比較的容易
Native App: 変更に対して比較的難儀

レスポンスのデシリアライズの方法によっては、最悪の場合クラッシュを催す。つらい。

盛り込んだ工夫

賞味期限の長いサービスを構築する時に、脳みそを振り絞って考えたこと。

API をバージョニングする
バージョン・ビルド番号を送ってもらう
- 特定のバージョンだけ振る舞いを変える
- ブラックリストで強制アップデート
メンテナンスモード
プロパティの追加に対して寛容になってもらう
接続先のサーバを変更可能にしてもらう

ここはもっとこうしたほうがいいとか情報があれば教えてください。

API のバージョニング

API をバージョニング将来の変更に備え、v1 から v2 への移行期は両バージョンを保守する。

パスで切り分ける方法
- /v1/foo/bar
- /v2/foo/bar
ヘッダで切り分ける方法
- Accept-Header: v1
- Accept-Header: v2

API そのもののバージョニングは、ネイティブアプリだけではなくウェブアプリに対しても有効なアプローチ。

バージョン・ビルド番号を送ってもらう

バージョン番号に基づいて以下のことが可能になる。

特定のバージョンだけ振る舞いを変える
ブラックリストで強制アップデート

バージョン番号はヘッダでやりとりする方法がスマート？

X-App-Version: 1.0.1
X-App-Build: 3

特定のバージョンだけ振る舞いを変える

バージョン番号を判定してリクエストの解釈、レスポンスの振る舞いを変更できる。

なるべくならそうしないほうが良い。バージョンごとの分岐が多くなりメンテナンスコストが増大してきたら v2 の出番かも。

ブラックリストで強制アップデート

Web API のバージョンアップなどで、特定のバージョン未満を deprecate したいときや、重篤なバグが含まれてしまったバージョンを最新版にアップグレードして欲しい時に有用。

クライアントは決められたレスポンスをもらったら、App Store なり Play Store のページに移動するように設計しておく。

なるべくならそうしないほうが (以下略

メンテナンスモード

あらかじめメンテナンスページを用意しておき、API が 500 番台を返した際にアプリ側で WebView 経由でページをモーダルで表示する。

計画的メンテナンス時 → メンテナンスの内容と終了時刻の告知
計画外でたまたま発生しちゃった時 → 混み合っております

サーバの障害時に影響しないよう、メンテナンスページはサーバとは別の場所に指定しておくと吉。例えば S3 とか。

ユーザ視点で見たとき「よくわからないけどアプリが動かない」ということが減らせる。応用すれば、サービスが終わっても遺言が残せる。

プロパティの追加に対して寛容になってもらう

クライアントは、(CSS のように) 知らないプロパティが出てきても無視するよう設計しておくことで、機能追加などに伴ってプロパティを追加するのが容易になる。

接続先のサーバを変更可能にしてもらう

デバッグが容易に！

iOS であれば、Debug ビルドは設定変更可能に、Release ビルドでは設定不能 (常に本番) を見るようにしてもらう。

まとめ

ネイティブアプリ側のバージョンアップは大変なので、逃げ道をたくさん作っておきましょう。

ご静聴ありがとうございました。

operando/api-server.md