Web APIのパージョン管理

Tuyoshi Akiyama
Aug 28, 2017 · 5 min read

前回の続きになります。今回は、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の扱い方についてです。

)
Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade