メインコンテンツへスキップ
バージョン: 最新版

APIバージョニング

APIバージョンの変更を適切に管理し、下位互換性を維持します。Omiseのバージョニング戦略、バージョンの指定方法、アップグレードのベストプラクティスについて学びます。

概要​

Omiseは日付ベースのAPIバージョニングを使用して、既存の連携を壊すことなく改善を導入します。各バージョンはリリース日（YYYY-MM-DD形式）で命名されます。連携が使用するAPIバージョンを制御して、安定性を確保し、自分のスケジュールでアップグレードを計画できます。

クイックスタート
  • 現在のバージョン: 2019-05-29
  • Omise-Versionヘッダーでバージョンを指定
  • ヘッダーなし = アカウントのデフォルトバージョン
  • バージョンは変更されない - 連携は安定したまま
  • 新機能が必要な時にアップグレードを計画

現在のAPIバージョン​

最新バージョン: 2019-05-29​

リリース日: 2019年5月29日

これはOmise APIの現在の安定バージョンです。すべての新しい連携はこのバージョンを使用する必要があります。

curl https://api.omise.co/charges \
  -u skey_test_...: \
  -H "Omise-Version: 2019-05-29"

バージョニングの仕組み​

バージョン形式​

Omise APIバージョンは日付ベースの命名を使用:

YYYY-MM-DD

例:

  • 2019-05-29 - 2019年5月29日リリース
  • 2017-11-02 - 2017年11月2日リリース
  • 2015-11-17 - 2015年11月17日リリース

APIバージョンの指定​

2つの方法でAPIバージョンを指定できます:

1. リクエストごとのヘッダー（推奨）​

Omise-Versionヘッダーを使用:

curl https://api.omise.co/charges \
  -u skey_test_...: \
  -H "Omise-Version: 2019-05-29" \
  -X POST \
  -d "amount=100000" \
  -d "currency=thb"

利点:

  • ✅ リクエストごとの明示的なバージョン制御
  • ✅ 新しいバージョンのテストが簡単
  • ✅ 異なる操作に異なるバージョンを使用可能
  • ✅ アカウントデフォルトを上書き

2. アカウントのデフォルトバージョン​

ダッシュボードでデフォルトバージョンを設定:

  1. Omiseダッシュボードにログイン
  2. 設定 → APIバージョンに移動
  3. バージョンを選択
  4. 保存

Omise-Versionヘッダーなしのすべてのリクエストはこのバージョンを使用します。

コードでのバージョン指定​

Ruby​

require 'omise'

Omise.api_key = ENV['OMISE_SECRET_KEY']
Omise.api_version = '2019-05-29'

# すべてのリクエストは指定されたバージョンを使用
charge = Omise::Charge.create({
  amount: 100000,
  currency: 'thb',
  card: token
})

Python​

import omise

omise.api_secret = os.environ['OMISE_SECRET_KEY']
omise.api_version = '2019-05-29'

# すべてのリクエストは指定されたバージョンを使用
charge = omise.Charge.create(
    amount=100000,
    currency='thb',
    card=token
)

Node.js​

const omise = require('omise')({
  secretKey: process.env.OMISE_SECRET_KEY,
  omiseVersion: '2019-05-29'
});

// すべてのリクエストは指定されたバージョンを使用
const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  card: token
});

cURL​

# ヘッダーでバージョンを指定
curl https://api.omise.co/charges \
  -u skey_test_...: \
  -H "Omise-Version: 2019-05-29" \
  -X POST \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "card=tokn_test_..."

破壊的変更 vs 非破壊的変更​

破壊的変更​

破壊的変更は新しいAPIバージョンでのみ導入されます:

例:

  • APIエンドポイントの削除
  • レスポンスフィールドの削除
  • レスポンスフィールドタイプの変更
  • 必須パラメータの変更
  • エラーコードの変更
  • 既存フローに影響する動作の変更

Omiseの対応:

  • ✅ 新しいバージョン（新しい日付）としてリリース
  • ✅ 古いバージョンは引き続き動作
  • ✅ 準備ができたらオプトイン
  • ✅ 移行ガイドを提供

非破壊的変更​

非破壊的変更はすべてのバージョンに追加される可能性があります:

例:

  • 新しいAPIエンドポイントの追加
  • 新しいレスポンスフィールドの追加
  • 新しいオプションパラメータの追加
  • 新しいエラーコードの追加
  • 新しいイベントタイプの追加
  • パフォーマンスの改善

対応方法:

  • ✅ レスポンスの未知のフィールドを無視
  • ✅ フィールドの順序に依存しない
  • ✅ 予期しない値を適切に処理
  • ✅ 本番に近いデータでテスト
前方互換性

新しいフィールドを適切に処理できるように連携を構築:

// ✅ 良い例 - 未知のフィールドを無視
const { id, amount, status } = charge;

// ❌ 悪い例 - 新しいフィールドが追加されると壊れる
const charge = { id, amount, status }; // これらのフィールドのみを想定

ベストプラクティス​

1. APIバージョンを明示的に固定​

# ✅ 良い例 - 明示的なバージョン
Omise.api_version = '2019-05-29'

# ❌ 悪い例 - アカウントデフォルトに依存
Omise.api_version = nil  # アカウントデフォルトを使用

理由:

  • ✅ 予期しない変更を防止
  • ✅ コードでバージョンが明確
  • ✅ アップグレードのテストが容易
  • ✅ 環境間で一貫

2. 環境変数を使用​

// ✅ 良い例 - 設定でバージョン指定
const omise = require('omise')({
  secretKey: process.env.OMISE_SECRET_KEY,
  omiseVersion: process.env.OMISE_API_VERSION || '2019-05-29'
});

利点:

  • ✅ コードデプロイなしで変更可能
  • ✅ 環境ごとに異なるバージョン
  • ✅ 設定の一元化

3. バージョンアップグレードを徹底的にテスト​

# バージョンアップグレード用テストスイート
class TestAPIVersion2019(unittest.TestCase):
    def setUp(self):
        omise.api_version = '2019-05-29'

    def test_charge_creation(self):
        charge = omise.Charge.create(
            amount=100000,
            currency='thb',
            card=token
        )
        self.assertEqual(charge.amount, 100000)

    def test_source_creation(self):
        source = omise.Source.create(
            type='promptpay',
            amount=100000,
            currency='thb'
        )
        self.assertIsNotNone(source.scannable_code)

クイックリファレンス​

現在のバージョン​

2019-05-29

バージョン指定​

# ヘッダーで
curl -H "Omise-Version: 2019-05-29" ...

# Rubyで
Omise.api_version = '2019-05-29'

# Pythonで
omise.api_version = '2019-05-29'

# Node.jsで
omise = require('omise')({ omiseVersion: '2019-05-29' })

# PHPで
define('OMISE_API_VERSION', '2019-05-29');

# Goで
client.APIVersion = "2019-05-29"

バージョン形式​

YYYY-MM-DD (例: 2019-05-29)

破壊的変更​

  • 新しいバージョンでのみ
  • 古いバージョンは安定したまま
  • アップグレードのタイミングは自分で制御
  • 移行ガイドを提供

非破壊的変更​

  • すべてのバージョンに追加される可能性
  • 新しいフィールド、エンドポイント、機能
  • 未知のフィールドを適切に処理
  • 前方互換性のあるコードを構築

関連リソース​

次へ: レート制限でAPI制限内に収まり、レート制限エラーを処理する方法を学びましょう。