Web APIのパージョン管理
前回の続きになります。今回は、APIのバージョニングについて、学習したことをまとめていきます。
まずは、次の2つの例を見ていきます。
# Request
GET http://api.example.com/users/12345 Accept: application/json; version=1# Response
HTTP/1.1 200 OK
Content-Type: application/json; version=1{“id”:”12345”, “name”:”Joe DiMaggio”}
上の例は、version1のAPIに対してのリクエストです。2つの要素(id, nameフィールド)の値が返ってきます。では、同じAPIのversion2はどうでしょうか。
# Request
GET http://api.example.com/users/12345 Accept: application/json; version=2# Response
HTTP/1.1 200 OK
Content-Type: application/json; version=2{“id”:”12345”, “firstName”:”Joe”, “lastName”:”DiMaggio”}
リソースを示すURIは同じです。URIのversionに当たる数字が2になるのが、リクエストの違いになります。また、返ってくるデータのフィールドも3つ(lastNameが追加)になり、変化します。
上の例は、 Content-Type 内のversionで対応したバージョニングです。もう一つの方法は、APIのURI自体にバージョン番号を含ませるものです。これはURIそのものを変えるものですから、version changeの影響が大きくなります。
では、リクエストにversion番号が含まれていない場合はどうでしょうか、その場合は、一番古いverison(上の例のversion=1)のリクエストとして扱います。また、サポートされないversionの場合は、406コード(Not Acceptable)とサポートしているversion情報を返します。
# Reques
GET http://api.example.com/users/12345
Content-Type: application/json; version=999# Response
HTTP/1.1 406 NOT ACCEPTABLE Content-Type: application/json[“application/json; version=1”, “application/json; version=2”, “application/xml; version=1”, “application/xml; version=2”]
次は、実際にどんな時に、versionを変えるのが良いのでしょうか?
次のケースに当てはまる時に、versioningを考慮されます。
- property名が変わる
- propertyを除いた
- propertyのdatatype(stringからintegerなど)を変えた
- 検証(Validation)を通る条件が変わった
- Atomスタイルのリンクで、「rel」値を変更した
- 要求されているリソースが、既存のworkflowに新しく組み込まれる
- リソースの意味、それ自体が元のオリジナルとは異なったものになる
- 既存のリソースを共通点にもつ、ある2つのリソースを一つにするとき
などが、挙げられます。これは一部の例で、その他の場合もケース・バイ・ケースで起こります。また、次の例は機能を壊す可能性がない変化の、場合になります。
- JSONリスポンスに新しいpropertyが追加
- 他のリソースへのリンクが、新しく追加
- 新しいcontent-typeの追加
- 新しいcontent-languageの追加
- 名前のケーシングはAPIを扱う上で、様々なケーシングを扱う為、関係性はありません
versioningはリソース毎に行われる行われるものになります。が、あるchange(workflowが変わる)に対しては、複数のリソースの変化が必要な場合もあります。
また、一度にサポートするversionの数は2つ以下に留めることが、大事になります。
廃止(Deprecated)されるという用語は、リソースがまだAPIによって利用可能であるが、利用できなくなり、今後存在しなくなることを伝達するために使用されています。
例えば、そのリクエストしたversion番号が、Deprecatedであった場合のデータは次のように返されます。
# Response
HTTP/1.1 200 OK
Content-Type: application/json; version=1
Deprecated: true以上が、APIのバージョニングのまとめになります。
次は、Date/Timeの扱い方についてです。
