- 2014/12/12
- nulltask @ いいオフィス
クライアントに対して XML や JSON などのフォーマットでレスポンスを返すサーバのこと。
- Web API で想定されるクライアント
- Web アプリケーション
- ネイティブアプリケーション
今日はネイティブアプリケーションでの実装時の注意を紹介します。
- Web App: 即時
- Native App: 即時ではない
すぐに変更を反映できない。つらい。
- Web App: キャンセル不可
- Native App: キャンセル可能
常に最新版を使ってもらえるわけではない。つらい。
- Web App: 変更に対して比較的容易
- Native App: 変更に対して比較的難儀
レスポンスのデシリアライズの方法によっては、最悪の場合クラッシュを催す。つらい。
賞味期限の長いサービスを構築する時に、脳みそを振り絞って考えたこと。
- API をバージョニングする
- バージョン・ビルド番号を送ってもらう
- 特定のバージョンだけ振る舞いを変える
- ブラックリストで強制アップデート
- メンテナンスモード
- プロパティの追加に対して寛容になってもらう
- 接続先のサーバを変更可能にしてもらう
ここはもっとこうしたほうがいいとか情報があれば教えてください。
API をバージョニング将来の変更に備え、v1 から v2 への移行期は両バージョンを保守する。
- パスで切り分ける方法
/v1/foo/bar/v2/foo/bar
- ヘッダで切り分ける方法
Accept-Header: v1Accept-Header: v2
API そのもののバージョニングは、ネイティブアプリだけではなくウェブアプリに対しても有効なアプローチ。
バージョン番号に基づいて以下のことが可能になる。
- 特定のバージョンだけ振る舞いを変える
- ブラックリストで強制アップデート
バージョン番号はヘッダでやりとりする方法がスマート？
X-App-Version: 1.0.1X-App-Build: 3
バージョン番号を判定してリクエストの解釈、レスポンスの振る舞いを変更できる。
なるべくならそうしないほうが良い。バージョンごとの分岐が多くなりメンテナンスコストが増大してきたら v2 の出番かも。
Web API のバージョンアップなどで、特定のバージョン未満を deprecate したいときや、重篤なバグが含まれてしまったバージョンを最新版にアップグレードして欲しい時に有用。
クライアントは決められたレスポンスをもらったら、App Store なり Play Store のページに移動するように設計しておく。
なるべくならそうしないほうが (以下略
あらかじめメンテナンスページを用意しておき、API が 500 番台を返した際にアプリ側で WebView 経由でページをモーダルで表示する。
- 計画的メンテナンス時 → メンテナンスの内容と終了時刻の告知
- 計画外でたまたま発生しちゃった時 → 混み合っております
サーバの障害時に影響しないよう、メンテナンスページはサーバとは別の場所に指定しておくと吉。例えば S3 とか。
ユーザ視点で見たとき「よくわからないけどアプリが動かない」ということが減らせる。応用すれば、サービスが終わっても遺言が残せる。
クライアントは、(CSS のように) 知らないプロパティが出てきても無視するよう設計しておくことで、機能追加などに伴ってプロパティを追加するのが容易になる。
デバッグが容易に！
iOS であれば、Debug ビルドは設定変更可能に、Release ビルドでは設定不能 (常に本番) を見るようにしてもらう。
ネイティブアプリ側のバージョンアップは大変なので、逃げ道をたくさん作っておきましょう。
ご静聴ありがとうございました。