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

API バージョニング

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

概要​

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

クイックスタート
  • 現在のバージョン: 2019-05-29
  • バージョンを指定するにはOmise-Versionヘッダーを使用
  • ヘッダーなし = アカウントのデフォルトバージョン
  • バージョンは決して変更されません - 統合は安定したまま
  • 新機能が必要な場合にアップグレードを計画

現在のAPIバージョン​

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

リリース日: May 29, 2019

これは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 - May 29, 2019リリース
  • 2017-11-02 - November 2, 2017リリース
  • 2015-11-17 - November 17, 2015リリース

APIバージョンの指定​

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

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. アカウント Default Version​

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

  1. Omise Dashboardにログイン
  2. Settings → API Versionに移動
  3. バージョンを選択
  4. 保存

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

バージョンの動作​

バージョンの仕組み​

  1. バージョンは不変 - バージョンの動作は決して変更されません
  2. 新しいバージョンは変更を導入 - 破壊的変更は新しいバージョンでのみ
  3. アップグレードを制御 - 新しいバージョンに明示的にオプトイン
  4. 古いバージョンをサポート - レガシーバージョンは引き続き利用可能

例 Timeline​

2015-11-17 → 統合を構築
    ↓
2017-11-02 → 新しいバージョンをリリース
    ↓        (統合は引き続き2015-11-17を使用)
    ↓
2019-05-29 → 新しいバージョンをリリース
    ↓        (統合は引き続き2015-11-17を使用)
    ↓
今日       → 2019-05-29にアップグレード
    ↓        (準備ができたらオプトイン)

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

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
)

PHP​

<?php
require_once 'vendor/autoload.php';

define('OMISE_SECRET_KEY', getenv('OMISE_SECRET_KEY'));
define('OMISE_API_VERSION', '2019-05-29');

OmiseCharge::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
});

Go​

package main

import (
    "github.com/omise/omise-go"
    "github.com/omise/omise-go/operations"
)

func main() {
    client, _ := omise.NewClient(
        os.Getenv("OMISE_PUBLIC_KEY"),
        os.Getenv("OMISE_SECRET_KEY"),
    )

    // APIバージョンを設定
    client.APIVersion = "2019-05-29"

    charge, _ := client.CreateCharge(&operations.CreateCharge{
        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_..."

破壊的変更と非破壊的変更​

破壊的変更​

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

例:

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

Omiseの処理方法:

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

非破壊的変更​

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

例:

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

処理方法:

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

新しいフィールドを適切に処理できるように統合を構築します:

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

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

バージョン履歴​

2019-05-29 (現在)​

リリース日: May 29, 2019

変更内容:

  • ソースオブジェクト構造の強化
  • エラーレスポンスの改善
  • チャージフロー処理の更新
  • Webhookイベントペイロードの改善
  • 決済方法オブジェクトの改良

2017-11-02からのマイグレーション:

  • ソースオブジェクトに追加フィールド
  • 一部のチャージステータス遷移の改良
  • イベントペイロードにより多くのコンテキストを含む
  • アップグレード後にすべての決済フローをテスト

2017-11-02​

リリース日: November 2, 2017

変更内容:

  • 代替決済のためのソースAPIの導入
  • 顧客オブジェクトの強化
  • 紛争処理の改善
  • スケジュールオブジェクトの追加
  • 振込ロジックの更新

2015-11-17からのマイグレーション:

  • 代替決済にはoffsiteの代わりにソースを使用
  • 顧客処理コードの更新
  • 紛争webhookのレビュー
  • スケジュールされた操作のテスト

2015-11-17​

リリース日: November 17, 2015

レガシーバージョン - 引き続きサポートされていますが、新しい機能がありません:

  • ソースAPIなし（古いoffsiteメソッドを使用）
  • 限定された決済方法
  • 古いイベント構造

推奨: 最高のエクスペリエンスのために2019-05-29にアップグレード

マイグレーションガイド​

アップグレードの計画​

  1. 新しいバージョンの変更履歴をレビュー
  2. 統合に影響する破壊的変更を特定
  3. 新しいバージョンでテストモードでテスト
  4. 変更に対応するためにコードを更新
  5. 本番環境の前に徹底的にテスト
  6. トラフィックの少ない時間帯に本番環境にデプロイ
  7. 問題を監視
  8. 安定したらアカウントのデフォルトを更新

新しいバージョンのテスト​

# 現在のバージョンと並行して新しいバージョンをテスト
def create_charge_v2019(params)
  charge = Omise::Charge.create(
    params,
    { 'Omise-Version' => '2019-05-29' }
  )

  # 違いをログに記録
  logger.info("New version charge: #{charge.to_json}")

  charge
end

def create_charge_current(params)
  charge = Omise::Charge.create(
    params,
    { 'Omise-Version' => '2017-11-02' }
  )

  logger.info("Current version charge: #{charge.to_json}")

  charge
end

# 結果を比較
new_charge = create_charge_v2019(charge_params)
old_charge = create_charge_current(charge_params)

compare_charges(new_charge, old_charge)

段階的なマイグレーション​

// 段階的なロールアウトのためにフィーチャーフラグを使用
const useNewAPIVersion = featureFlags.isEnabled('api-version-2019');

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

// 両方のバージョンを監視
if (useNewAPIVersion) {
  analytics.track('api_version_2019_used');
}

バージョン検出​

# レスポンスで使用されたバージョンを検出
def get_api_version_from_response(response_headers):
    return response_headers.get('Omise-Version')

# 例
response = omise.Charge.retrieve('chrg_test_...')
version = get_api_version_from_response(response.headers)
print(f"Response from API version: {version}")

非推奨ポリシー​

非推奨の仕組み​

  1. 新しいバージョンをリリース（変更あり）
  2. 古いバージョンは引き続き動作（即座の影響なし）
  3. 非推奨を発表:
    • メール通知
    • ダッシュボード通知
    • API変更履歴
    • 開発者ドキュメント
  4. マイグレーション期間（通常12ヶ月以上）
  5. サポート終了警告（サンセットの6ヶ月前）
  6. バージョンのサンセット（古いバージョンが動作しなくなる）

非推奨タイムラインの例​

月0:  新しいバージョンをリリース (2019-05-29)
      古いバージョン (2017-11-02) は引き続き動作

月1:  非推奨を発表
      マイグレーションガイドを公開

月6:  リマインダー通知を送信

月12: 最終警告 (サンセットまで6ヶ月)

月18: バージョン2017-11-02のサンセット
      バージョンヘッダーのないリクエストは2019-05-29を使用

非推奨の確認​

# レスポンスヘッダーで非推奨警告を確認
curl -i https://api.omise.co/charges \
  -u skey_test_...: \
  -H "Omise-Version: 2017-11-02"

# 非推奨ヘッダーを探す
# Omise-Deprecated: true
# Omise-Sunset: 2025-12-31
# Omise-Recommended-Version: 2019-05-29

ベストプラクティス​

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)

    def test_customer_with_card(self):
        customer = omise.Customer.create(
            email='test@example.com',
            card=token
        )
        self.assertIsNotNone(customer.default_card)

4. 未知のフィールドを適切に処理​

// ✅ 良い - 防御的な解析
function parseCharge(chargeData) {
  return {
    id: chargeData.id,
    amount: chargeData.amount,
    currency: chargeData.currency,
    status: chargeData.status,
    // 将来の互換性のために未知のフィールドを保存
    _raw: chargeData
  };
}

// ❌ 悪い - 固定された構造を想定
function parseChargeBad(chargeData) {
  const { id, amount, currency, status } = chargeData;
  return { id, amount, currency, status };
  // 構造が変更されると壊れる
}

5. APIバージョン使用状況を監視​

# 監視のためにAPIバージョンをログに記録
class OmiseLogger
  def self.log_request(endpoint, version)
    Rails.logger.info({
      event: 'omise_api_request',
      endpoint: endpoint,
      api_version: version,
      timestamp: Time.now.iso8601
    }.to_json)
  end
end

# リクエストで使用
OmiseLogger.log_request('/charges', '2019-05-29')
charge = Omise::Charge.create(params)

6. コード内にバージョンを文書化​

<?php
/**
 * Omise API統合
 *
 * APIバージョン: 2019-05-29
 * 最終更新: 2025-01-15
 * マイグレーションガイド: https://docs.omise.co/api-versioning
 *
 * 重要: APIバージョンをアップグレードする場合:
 * 1. 変更履歴をレビュー
 * 2. すべての決済フローをテスト
 * 3. Webhookハンドラーを確認
 * 4. このコメントを更新
 */
class OmisePayment {
    const API_VERSION = '2019-05-29';

    public function createCharge($params) {
        return OmiseCharge::create($params, [
            'Omise-Version' => self::API_VERSION
        ]);
    }
}

7. CI/CD内のバージョン​

# .env.example
OMISE_API_VERSION=2019-05-29

# docker-compose.yml
version: '3.8'
services:
  app:
    environment:
      - OMISE_API_VERSION=${OMISE_API_VERSION}

# GitHub Actions
- name: Run tests
  env:
    OMISE_API_VERSION: 2019-05-29
  run: npm test

バージョンアップグレードチェックリスト​

新しいAPIバージョンにアップグレードする前に:

アップグレード前​

  • 新しいバージョンの完全な変更履歴をレビュー
  • すべての破壊的変更を特定
  • コードが非推奨機能を使用しているか確認
  • マイグレーションガイドをレビュー
  • 依存関係（SDKライブラリ）を更新
  • ロールバック戦略を計画

テスト​

  • 新しいバージョンヘッダーでテストモードでテスト
  • すべての決済フロー（カード、代替決済）をテスト
  • 顧客の作成と管理をテスト
  • 返金操作をテスト
  • 振込操作をテスト
  • Webhookペイロード処理を検証
  • エラー処理をテスト
  • 重要なパスの負荷テスト
  • 古いバージョンとレスポンスを比較

デプロイ​

  • コード内のAPIバージョンを更新
  • ステージング環境にデプロイ
  • スモークテストを実行
  • エラー率を監視
  • 本番環境にデプロイ（トラフィックの少ない時間帯）
  • ダッシュボードを監視
  • Webhook配信を確認
  • 決済成功率を検証

アップグレード後​

  • 24〜48時間監視
  • ログの異常をレビュー
  • エラー率を確認
  • レポートの精度を検証
  • ドキュメントを更新
  • アカウントのデフォルトバージョンを更新（オプション）
  • コード変更を文書化
  • チームに変更をトレーニング

バージョン問題のトラブルシューティング​

バージョン不一致エラー​

問題: バージョン変更後の予期しない動作またはエラー

解決策:

# 使用されているバージョンを確認
def debug_api_version
  # テストリクエストを作成
  response = Omise::Account.retrieve

  # レスポンスヘッダーを確認
  version = response.http_headers['Omise-Version']
  puts "API Version used: #{version}"

  # クライアント設定を確認
  puts "Client version: #{Omise.api_version}"

  # アカウントのデフォルトを確認
  puts "Check Dashboard Settings → API Version for account default"
end

レスポンス構造の違い​

問題: フィールドが欠落または異なるタイプ

解決策:

# バージョン間のレスポンスを比較
def compare_versions(operation_fn):
    # バージョン1
    omise.api_version = '2017-11-02'
    response_v1 = operation_fn()

    # バージョン2
    omise.api_version = '2019-05-29'
    response_v2 = operation_fn()

    # 比較
    print("Version 2017-11-02:")
    print(json.dumps(response_v1, indent=2))

    print("\nVersion 2019-05-29:")
    print(json.dumps(response_v2, indent=2))

    # 違いを見つける
    diff = deepdiff.DeepDiff(response_v1, response_v2)
    print("\nDifferences:")
    print(json.dumps(diff, indent=2))

# 使用法
compare_versions(lambda: omise.Charge.retrieve('chrg_test_...'))

SDKバージョンの互換性​

問題: SDKが新しいAPIバージョンをサポートしていない

解決策:

# SDKバージョンを確認
# Ruby
gem list omise

# Python
pip show omise

# Node.js
npm list omise

# 最新版に更新
# Ruby
gem update omise

# Python
pip install --upgrade omise

# Node.js
npm update omise

よくある質問​

バージョンを指定しない場合はどうなりますか？

リクエストはアカウントのデフォルトAPIバージョン（ダッシュボードで設定）を使用します。デフォルトが変更されると、一貫性のない動作につながる可能性があります。常にコード内でバージョンを明示的に指定してください。

異なるリクエストに異なるバージョンを使用できますか？

はい！ Omise-Versionヘッダーを使用して、リクエストごとに異なるバージョンを指定できます。これは、既存の統合と並行して新しいバージョンの動作をテストするマイグレーション中に役立ちます。

# リクエスト1 - 古いバージョン
curl -H "Omise-Version: 2017-11-02" ...

# リクエスト2 - 新しいバージョン
curl -H "Omise-Version: 2019-05-29" ...
新しいバージョンはどのくらいの頻度でリリースされますか？

Omiseは、重要な改善または必要な破壊的変更が行われた場合にのみ、新しいAPIバージョンをリリースします。バージョンはリリース後何年もサポートされます。現在のバージョン（2019-05-29）は2019年から安定しています。

新しいバージョンがリリースされたらすぐにアップグレードする必要がありますか？

いいえ。 現在のバージョンは引き続き動作します。独自のスケジュールでアップグレードできます:

  • 新機能のためにアップグレード
  • 古いバージョンのサンセット前にアップグレード
  • 計画されたメンテナンスウィンドウ中にアップグレード

通常、非推奨の発表からアップグレードまで18ヶ月以上あります。

アップグレードしないと統合が壊れますか？

すぐには壊れません。 統合は現在のバージョンで引き続き動作します。ただし:

  • 新機能は利用できません
  • 最終的に古いバージョンはサンセットされます（18ヶ月以上の通知あり）
  • セキュリティの改善にはアップグレードが必要な場合があります

定期的なバージョンレビュー（6〜12ヶ月ごと）を計画してください。

バージョンが非推奨になったことをどのように知ることができますか？

Omiseは以下の方法で通知します:

  • アカウント所有者へのメール
  • ダッシュボード通知
  • レスポンスヘッダー（Omise-Deprecated: true）
  • API変更履歴
  • 開発者ドキュメント

ログ内の非推奨ヘッダーの監視を設定してください。

本番環境に影響を与えずに新しいバージョンをテストできますか？

はい！ Omise-Versionヘッダーを使用します:

  1. 本番環境は現在のバージョンに保持（アカウントのデフォルト）
  2. ステージングでヘッダーを使用して新しいバージョンをテスト
  3. バージョンを比較する並列テストを実行
  4. 準備ができたら本番環境をアップグレード
# 本番環境（アカウントのデフォルトを使用）
Omise::Charge.create(params)

# ステージング（新しいバージョンをテスト）
Omise::Charge.create(
  params,
  { 'Omise-Version' => '2019-05-29' }
)

クイックリファレンス​

現在のバージョン​

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制限内に収め、レート制限エラーを処理する方法を理解します。