Skip to main content

APIバージョニング

ケンオールは積極的にAPIの機能拡張を行ってきておりますが、同時にさまざまなお客様の開発要件にお応えするため、APIレスポンスの互換性を非常に重視しております。

マイナーバージョンアップの際は基本的に前バージョンのAPIリクエスト/レスポンスペイロードの形状を保った形を取るよう細心の注意を払っておりますが、正規化ロジックの変更など、ペイロードの内訳が変わるケースなどに対応すべく、APIのバージョニングを導入しました。

APIバージョニングとは、ダッシュボード、リクエストURLやリクエストヘッダ、クエリーパラメーターなどでバージョンを指定することで、ケンオールの特定の時点の仕様に則った形でAPIの利用を続けられるというものです。これにより、お客様の側でAPIの変更にすぐ追従できない場合でも暫定措置として一定期間は旧バージョンを使い続けることができます。

APIのメジャーバージョンとマイナーバージョンについて​

APIのメジャーバージョンとは、エンドポイントのURLに含まれる /v1 の部分に該当する文字列が指すものです。一方、マイナーバージョンはその機能が導入された日付を反映した YYYY-MM-DD 形式の文字列で表されるもので、本ドキュメントで「APIバージョン」という呼称を用いた場合には、このマイナーバージョンを指します。

基本的に何らかのバージョンが上がる変更が発生した場合にはマイナーバージョンが更新されていきますが、以下のタイミングでメジャーバージョンのアップグレードが行われることがあります。

  • マイナーバージョンが多数累積した場合
  • 変更事項が10点を超えるような大規模な変更が行われる場合

バージョンが上がるAPIの変更について​

以下のケースではAPIバージョンが上がる想定となっています。

  • APIリクエスト
    • リクエストパラメータの意味に変更があった
    • リクエストパラメータが削除された
    • 必須のリクエストパラメータが追加された
  • APIレスポンス
    • レスポンスの形式が変更された (プロパティの追加、削除、データ型の変更など)
    • レスポンスプロパティの意味に変更があった

一方、以下のケースではAPIバージョンが上がらない想定となっています。

  • APIリクエスト
    • 任意のリクエストパラメータが追加された
  • APIレスポンス
    • レスポンスの文字種など表面的な内容の変更のうち、用途を鑑みて互換性を損ねると言えないもの

バージョンの指定方法​

メジャーバージョンはリクエストURLのパスの一部として指定します。本APIドキュメントでは、各エンドポイントについてメジャーバージョンを含むリクエストURLの全部を記述しているため、特殊な状況を除いて言及はしておりません。

一方、マイナーバージョンは以下の方法で指定することができます。

  • HTTPリクエストヘッダによる方法 (推奨)
  • クエリパラメータによる方法
  • APIキーごとに設定可能なデフォルト値

HTTPリクエストヘッダによる方法​

KenAll-API-Version リクエストヘッダを含めることで、バージョンを指定することができます。

例:

KenAll-API-Version: 2022-09-01

クエリパラメータによる方法​

クエリパラメータ -kenall-api-version を与えることで、バージョンを指定することができます。

例:

https://api.kenall.jp/v1/postalcode?q=...&-kenall-api-version=2022-09-01

APIキーごとに設定可能なデフォルト値​

上記いずれの方法でもバージョンが指定されなかった場合は、APIキーごとに設定可能なデフォルト値が使われます。設定方法はAPIキーの管理を参照してください。