この記事は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キーはデフォルトで最新バージョンが設定されます。
詳細はドキュメントを参照してください。
（Shodoで執筆されました）
