APIバージョニングを導入しました

この記事は2022年11月リリースでリリースされた機能の1つ、APIバージョニングについて紹介しています。

APIバージョニングとは、APIの仕様変更の都度付加されるマイナーバージョンをAPIリクエスト時にHTTPヘッダなどの方法で指定することで、過去のケンオールAPI仕様に遡ってAPIを利用できるようにするための仕組みです。

APIバージョニングを用いることで、全てのお客様はサポート対象である任意のバージョンを指定してレスポンスを受け取れます。

例えば郵便番号検索APIhttps://api.kenall.jp/v1/postalcode/1000001をリクエストすると、現在の最新版であるバージョン2022-11-01では以下のようなレスポンスを返します。

{
  "version": "2022-10-31",
  "data": [
    {
      "jisx0402": "13101",
      "old_code": "100",
      "postal_code": "1000001",
      "prefecture_kana": "トウキョウト",
      "city_kana": "チヨダク",
      "town_kana": "チヨダ",
      "town_kana_raw": "チヨダ",
      "prefecture": "東京都",
      "city": "千代田区",
      "town": "千代田",
      "koaza": "",
      "kyoto_street": "",
      "building": "",
      "floor": "",
      "town_partial": false,
      "town_addressed_koaza": false,
      "town_chome": false,
      "town_multi": false,
      "town_raw": "千代田",
      "corporation": null,
      "town_jukyohyoji": false,
      "update_status": 0,
      "update_reason": 0,
      "prefecture_roman": "Tokyo",
      "county": "",
      "county_kana": "",
      "county_roman": "",
      "city_without_county_and_ward": "千代田区",
      "city_without_county_and_ward_kana": "チヨダク",
      "city_without_county_and_ward_roman": "Chiyoda-ku",
      "city_ward": "",
      "city_ward_kana": "",
      "city_ward_roman": "",
      "city_roman": "Chiyoda-ku",
      "town_roman": "Chiyoda"
    }
  ]
}

新しいレスポンスを自社システムに適用したくない場合、バージョン2022-09-01を指定することで旧バージョンそのままのレスポンスを受け取れます。

https://api.kenall.jp/v1/postalcode/1000001?-kenall-api-version=2022-09-01とリクエストすると、以下のようなレスポンスとなります。

{
  "version": "2022-10-31",
  "data": [
    {
      "jisx0402": "13101",
      "old_code": "100",
      "postal_code": "1000001",
      "prefecture_kana": "トウキョウト",
      "city_kana": "チヨダク",
      "town_kana": "チヨダ",
      "town_kana_raw": "チヨダ",
      "prefecture": "東京都",
      "city": "千代田区",
      "town": "千代田",
      "koaza": "",
      "kyoto_street": "",
      "building": "",
      "floor": "",
      "town_partial": false,
      "town_addressed_koaza": false,
      "town_chome": false,
      "town_multi": false,
      "town_raw": "千代田",
      "corporation": null
    }
  ]
}

バージョン指定の方法はHTTPリクエストヘッダーやクエリパラメーターでの指定の他、APIキー単位でのデフォルトバージョンの指定も可能です。

本機能のリリース時点では、互換性維持のため、全既存ユーザーの作成済みAPIキーのデフォルトバージョンを2022-09-01を設定しています。 新規ユーザーのAPIキーや既存ユーザーが新規に作成したAPIキーはデフォルトで最新バージョンが設定されます。

詳細はドキュメントを参照してください。