JavaScript APIやWebサービスAPIはバージョン化が必要 - 開発者指摘

Yahoo!の技術者でありJavaScript関連の技術紹介に定評のあるNicholas C. Zakas氏がNCZOnlineにおいて、パブリックに公開されているWebサービスはバージョン管理されたAPIを提供すべきだといった内容の記事を公開した。依然として多くのWebサービスがバージョン管理されていない状況で提供されており、開発において不利益を被っているという内容になっている。

デスクトップやサーバの開発で利用されるライブラリはバージョン管理されていることが多い。メジャーバージョンアップは機能の変更を含み、マイナーバージョンアップはバグ修正や改善、セキュリティ対策などを含むなど、それぞれに規則があり提供されている。Webサービスとして提供されているAPIはこの発想が薄いものが多いという。

Nicholas C. Zakas氏は例としてHTMLを返すAPIを想定。たとえば、APIをコールしたあとに返ってくるHTMLデータの内容を解析して表示するプログラムを組んだとする。これが翌日には、HTMLではなくJSONを返すように変わってしまったら、表示はめちゃくちゃになってしまう。API的にHTMLを返すよりもJSONデータを返す方が合理的であったとしても、こうした既存のプログラムを動作不能にするような変更はしてはいけないという。こうした変更をしたければ、バージョンを変えればいいと説明する。既存のバージョンでは機能は変更しない、変更した機能は別のバージョンとして提供し、既存のユーザには影響を与えないようにすればいいというわけだ。

APIをバージョン管理する場合、どういった指針でバージョン番号を変更するのか、まず最初に検討する必要がある。氏は次の指針を紹介している。

• 既存の実装に対して動作を変えてしまうような変更をする場合にはバージョンを変更し、そうでない場合には変更しない。
• オプションパラメータに新しいパラメータを追加するような場合、バージョンの変更は必要ない。
• レスポンスフォーマットにフィールドを追加するような場合、バージョンの変更は必要ない。
• 必須パラメータとして新しいパラメータを追加するような場合、バージョンの変更が必要。
• レスポンスフォーマットのフィールド名を変更するような場合、バージョンの変更が必要。
• バグ修正などは、どこまで変更が及ぶかによってケースバイケースで判断。

基本的には、既存のプログラムの動作が変わるような場合にはバージョンを変更し、既存のバージョンはそのままにし、変更したものは別のバージョンとして提供するというスタイルになる。公開された記事では、バージョン管理の例としてJavaScript APIを提供する場合の管理指針の例も紹介している。紹介されている指針は次のとおり。

• API利用者に連絡が取れるようにしておく。たとえばAPIキーを使う、それをメールアドレスに結びつけておくなど。
• 少なくとも2つ前のバージョンまではメンテナンスするように計画する。
• 少なくとも1つ前のバージョンまでは後方互換性を確保する。まず新しいバージョンで非推奨APIに変更し、その次のバージョンで削除を実施する。新しいバージョンでいきなり削除しない。
• 少なくとも以前のバージョンは6ヶ月はサポートするようにする。
• 新しいバージョンをリリースした場合、利用者にその旨を通知し、アップグレードのスケジュールなども報告する。
• 古いバージョンの利用をモニタリングするようにする。古いバージョンを削除する1ヶ月前、2週間前に利用者にその旨を通知する。

バージョン管理の基本はいきなり変更しない、利用者にできるだけ連絡できる体制を整えておく、といった内容になっている。