GH GambleHub

テクノロジーとインフラストラクチャ→APIバージョン管理

APIバージョン管理

1）なぜそれを必要とします

バージョニングは、故障なくサービスと顧客間の契約を変更する管理可能な方法です。多数の統合製品（支払い、KYC/AML、ゲーム、請求、レポート）では、「古い」と「新しい」顧客が同時に住んでいます。正しいバージョンポリシー：
  • リリース中のインシデントのリスクを軽減します、
  • 改善および安全をスケジュールすることを可能にします、
  • パートナー移行のための予測可能なタイムラインを企業に提供します。

2）変更の分類

PATCH （not breaking）：コントラクトを変更せずに修正（オプションフィールドの追加、検証修正）。
MINOR：バックコンパチブル拡張（新しいエンドポイント、デフォルトのフィールド）。
MAJOR （breaking）：構造、セマンティクスを変更するか、フィールド/エンドポイントを削除します。

SemVer 'MAJORをお勧めします。マイナー。PATCH 'for artifacts （SDK/スキーマ）、 「external」 API番号は簡略化できます（v1、 v2）。

3） RESTバージョン管理モデル

1.URIへ：

'GET/v1/payments/{ id}'

長所：透明、キャッシュ可能、ルーティングが簡単。短所：ドキュメントの複製、微妙に進化することがより困難。

2.ヘッダー（コンテンツネゴシエーション）で：

'Accept： application/vnd。会社を設立しました。支払い。v2+json'

長所：柔軟性、URLの「ゴミ」なし、メディアタイプの便利な進化。短所：ブラウザでデバッグすることはより困難ですが、規律あるクライアントが必要です。

3.カスタムヘッダーで：

'X-API-Version： 2' （'Api-Version： 2025-09-01'）

長所：ちょうどスライスで。短所：標準性はなく、キャッシュに注意してください。

4.日付ベースのバージョン：

フィンテック/レポートに適しています：変更の予測可能な「カット」（例：四半期ごとに）。

5.リソース/モデルのバージョン管理：

同じエンドポイントが異なるビューを返すことができます：'fields=……'または'profile=lite「フル」これは追加であり、バージョン管理の代替ではありません。

推奨事項：外部統合の場合-'URI vN'+Rejection/Sunsetヘッダー；内部-ゲートウェイとプラットフォームがサポートしている場合、'Accept'またはバージョンヘッダーを使用できます。

4） GraphQL

設定-グローバルバージョンはありません。フィールド/タイプとdeprictionの追加による進化（'@deprecated （reason： ……"")').

変更の破棄-マイグレーションガイドを使用した「大規模な」ウィンドウ（バージョン管理されたスキーマ名前空間）のみ。
「n+1」を監視し、既存のフィールドの意味を変更しないでください。

5） gRPC/Protobuf

フィールド番号は不変です。削除されたフィールドを「予約済み」としてマークします。
セーフデフォルトでオプションとしてフィールドを追加します。
自動互換性チェックにはbuf breaking/lintを使用します。
バージョンパッケージ/モジュール：'パッケージ支払い。v1；'→'支払い。v2'。

6） イベントAPI （EDA）

イベントスキームは同じ契約です。スキーマレジストリ（Avro/JSON-Schema/Protobuf）に保存します。
トピックとバージョン：'支払い。v1。認可された、支払い。v2。承認されました。
変更を破る-新しいタイプのイベントまたは新しいトピック。
進化保証：LTS期間中の消費者向けの下位互換性。

7）減価償却方針とEOL

透明なルールを実装する：
  • 廃止：changelogおよびin specifications （OpenAPI/GraphQL SDL）のラベル、ヘッダー
  • 「うつ病：真実」と可能な場合「日没：火曜日、31 Mar 2026 00：00：00 GMT」。
  • コミュニケーション：電子メール/パートナーポータル、webhooks通知、リリースノート。
  • 用語：マイナー-サポートの3-6ヶ月、MAJOR-9-18ヶ月（批判に応じて）。
  • 時間ウィンドウ：「APIバージョン管理ポリシー」で修正します。

8）ルーティングとリリース

ゲートウェイAPI （Kong/Apigee/Nginx/Envoy）：プレフィックス'/v1/'、ヘッダーまたはメディアタイプによるルール。

ルート例： 

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow：トラフィックの1〜5％に新しいバージョンをロールし、コントラクトエラーのメトリックとログを比較します。
フィーチャーフラグ：コントラクトを変更せずに挙動を非表示にします。
ゼロダウンタイム移行：MAJORでは、データスキーマの二重書き込み/読み取りを提供します。

9）契約のテストおよび両立性制御

OpenAPI Diff（またはswagger-diff）-MINOR/PATCHがスキーマを壊さないことを確認します。
スペクトルリンティング-スタイル、必須メタデータ（バージョン、非推奨）。
消費者主導の契約（協定）-プロバイダが顧客を破らないようにします。
BUFブレイクプロトブフ。
CIはMAJORを上げることなく変化を断ち切るべきです。

10）ドキュメントとSDK

バージョン：'/docs/api/v1/openapi。json'、'/docs/api/v2/……'。
SemVerとchangelogを使用してバージョン（npm/maven/pypi）でSDKを生成します。
SDKの非推奨メソッドを非推奨アノテーション/非推奨アノテーションでマークします。

11）バージョンによる観察

メトリックを個別に収集：
  • バージョンごとのRPS/レイテンシ/エラー （'api_version'ラベル）。
  • エンドポイントの使用状況マップ：v1で他に誰が表示されますか？
  • アラート：「契約の不一致による>10％ 4xx」、「古い顧客>T日付後のX％」。

12）キャッシュとバージョン

トランジットバージョンでは、CDNキャッシュ性が向上します。

ヘッダー/メディアバージョンで-Varyで慎重に：
  • 'Vary： Accept、 X-API-Version'。
  • MINORのレスポンスのセマンティクスを変更してキャッシュキーを壊しないでください。

13）安全性

バージョンをJWTに暗号化またはステッチしないでください-バージョンはトークンではなくリクエストによって決定されます。
内部アセンブリ番号を明らかにしないでください。外部メッセージには「v1/v2」を使用します。
MAJORでは、レビュー検証、制限、PIIマスキング。

14）移行と自動ヘルパー

パブリッシュ「Migration Guide v1→v2」：フィールドマッピングテーブル、サンプルリクエスト/レスポンス、エッジケース。
古くなったフィールドを強調するクライアント（CLI）用のLinterを提供しています。
大規模なパートナー-2つのバージョンとテストデータセットを持つサンドボックス。

15）アンチパターン

「Eternal v1」：期限と使用基準の欠如。
MINOR/PATCHの非表示のブレイクチェンジ。
「クエリ文字列のバージョン」（'？v=2'）-キャッシュと可読性を遮断します。
「1つのエンドポイントは100のフラグ値」：テスト/ドキュメントが困難です。

16）実装チェックリスト

1.外部および内部クライアントのモデル（URI/Accept/Header）を選択します。
2.仕様とSDKのSemVer、 CIの自動ブレークチェック。
3.廃止/日没ポリシーとコミュニケーションテンプレート。
4.ゲートウェイルーティング+カナリア、バージョン別ダッシュボード。
5.重要な統合（支払い、KYC、レポート）のためのCDC/Contractテスト。
6.ドキュメント/SDK/移行ガイドは、リリースと同時に公開されます。
7.日付と責任を持つEOL計画。

17）例

17.1 REST （URI+ヘッダ）

リクエスト： 

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f
答え： 
json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}
減価償却ヘッダ（v1上）： 

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17.2コンテンツネゴシエーション


GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17.3 GraphQL （Field Depriction）

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17.4gRPC （protobuf）

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17.5イベントモデル

トピックス：
  • 'wallet。v1。バランス。更新されました'
  • 'wallet。v2。バランス。changed'（拡張スキーマを持つ新しいイベント）

スキームはレジストリに保存され、プロデューサーは互換性に違反するスキームでイベントを公開しません。

18） コンテキストiGaming/fintech（練習）

支払い：'status'/'decline_reason'が拡張された新しいPSPのv2を入力します。ゲートウェイ上で、レポート用にv1→v2をマッピングします。
KYC： MINORはフィールド'pep_screening'を追加し、クライアントはv1、 v2を無視します。
責任あるゲーム/制限：MAJORは制限モデル（毎日/毎週）を変更します。EOL v1以前のレポートへのダブルエクスポート。
レギュレータへのレポート：固定バージョンの日付：'reporting-2025-01'。

19）ミニポリシー（wikiの例）

モデル：外部API-'URI/vN/'；for internal-'Accept：……vN+json'または'X-API-Version： N'。
SemVer：仕様とSDKは'N。マイナー。パッチ'。MAJORにはRFC/ADRが必要です。
互換性：MINOR/PATCH-変更を破ることはありません。Breaking→MAJORのみ。
廃止/EOL： ≥ 90日間の発表；見出しの日没日；重要な顧客のためのLTSブランチ。
コントロール：OpenAPI diff/buf breaking in CI、 CDC for key integration。
観測可能性：metrics/logs with label 'api_version'。
リリース：カナリア5％ ≥ 24時間、そしてグリーンメトリックで100％に段階的に。

［結果］

バージョン管理は「/v2 in URL「ではなく、明示的な進化規則、自動互換性チェック、管理されたリリース、統合の尊重などのプロセスについてです。明確なポリシーを入力し、監視と監視を自動化します。変更は製品にとって脅威ではなくなります。

Contact

お問い合わせ

ご質問やサポートが必要な場合はお気軽にご連絡ください。いつでもお手伝いします！

統合を開始

Email は 必須。Telegram または WhatsApp は 任意。

お名前 任意
Email 任意
件名 任意
メッセージ 任意
Telegram 任意
@
Telegram を入力いただいた場合、Email に加えてそちらにもご連絡します。
WhatsApp 任意
形式：+国番号と電話番号（例：+81XXXXXXXXX）。

ボタンを押すことで、データ処理に同意したものとみなされます。