設計変更をしやすいWeb API を作る

今回は重要なポイントは多いが、疑問や問題点はなかったので、各章を一言でまとめて終わろうと思う。

設計変更のしやすさの重要性
- 外部に公開しているAPIの場合
  利用者が多く、利用者がきちんと対応できるようにするなどAPI の変更は超大変！
- モバイルアプリケーション向けAPI の場合
  外部公開よりは楽だが、それでもOSのバージョンがあげられないなどAPI の変更は結構大変！
- ウェブサービス上で使っているAPI の場合
  ウェブも自分のものなので楽だが、それでもキャッシュされているなどちょっと大変！
  
  そうじて「一度公開をしたWeb APIの仕様を変更するのはいずれにせよ問題が発生する危険性がある」ということ。
API をバージョンで管理する
以下のパターンがあるが、一般的に使われるのはURIにバージョンを埋め込む方法。
- URI にバージョンを埋め込む
- バージョンをクエリ文字列を入れる
- メディアタイプでバージョンを指定する
バージョン番号をどうつけるか
以下が一般的。

メジャーバージョン	マイナーバージョン	パッチバージョン
後方互換性のない変更が行われた場合	後方互換性のある機能変更、あるいは特定の機能が今後廃止されることが決まった場合	ソフトウェアのAPI に変更がないバグ修正などを行った場合

（メジャー）バージョンを変える際の指針
後方互換性を保つことが可能な変更は可能な限り、同じバージョンでのマイナーバージョンアップで対応し、バージョンをあげるのはどうしても後方互換性を保ったまま修正を行うことが難しい変更を加えなければならないときのみ、メジャーバージョンをあげる。
API の提供を終了する
Twitter の例のように以下の対応が必要！
- 新しいAPI の告知
- 旧API を廃止するという継続的な告知
- Blackout Test と呼ばれる一時的に旧API を停止してアクセスできないようにするテスト
あらかじめ提供終了時の仕様を盛り込んでおく
提供終了した場合に例えば410エラー（Gone）を返す、など提供終了時の仕様を決めておく。
利用規約にサポート期限を明記する
一定期間はAPI のバージョンをサポートする、と名言する。サービスの目的により、保証とサービス提供の範囲の明確化が重要な場合は有効。
オーケストレーション層
汎用的なAPI はどうしても使い方が煩雑になる。例えば１つのアクションを行うのに複数のAPI にアクセスしなければならなかったり、不要なデータを受け取らなければならずペイロードが大きくなってしまう。

サーバ側の汎用的なAPI とクライアントの間に"Client Adapter Code"を実行するオーケストレーション層をはさんで、さまざまなデバイスに対応できるようにする。

このオーケストレーション層を作成するのはクライアント側のエンジニアで、クライアント側のデバイス機能やリリースサイクルに合わせて、エンドポイントを修正できる。

Netflix のブログ記事 The Netflix Tech Blog: The Netflix Dynamic Scripting Platform によれば、
しっかりとしたデバイス開発者用エンドポイント管理ツールが提供されており、いわば社内専用PaaS として提供されているらしい。

さすがNetflix、はうらやましい限りですね！

AHA_oretamaの日記

WEB API The Good Parts ５章の自分的まとめ

設計変更をしやすいWeb API を作る