RTC のバージョンAPI管理
当サービスの /v1 お約束
Section titled “当サービスの /v1 お約束”以下のすべての項目 /v1 変更点 追加的にのみ. RTCは以下を追加する場合があります:
- 新しいルート、オプションのリクエストフィールド、およびクエリパラメータ;
- 新しいレスポンスフィールド、エラーコード、Webhookイベントタイプ、および列挙型値;
- 新しいレスポンスヘッダー。
未知のフィールドを無視し、未知のエラーコードを そのHTTPステータスの汎用コードとして扱うクライアントを構築してください。RTCは、フィールドの削除や名称変更、 型や意味の変更、オプション入力の必須化、または エラーコードの再利用を行いません。 /v1.
互換性を損なう変更は、新しいメジャーパスとして提供され、 /v2. その後、両方のバージョンが 並行して運用されます。 少なくとも12ヶ月間 以前 /v1 は廃止され、その旨は本 サイトに掲載されています。
レスポンスのシェイプを固定するには RTC-Version
Section titled “レスポンスのシェイプを固定するには RTC-Version”一部の改善により、回答の「意味」は変わらないものの、その「形式」が変更される場合があります。 例えば、 構造化されたエラーエンベロープ。これらは、日付付きバージョンヘッダーを使用して、 リクエストごとにオプトイン方式で適用されます:
RTC-Version: 2026-11-01| バージョン | 変更点 |
|---|---|
| なし | 元のシェイプ。エラーは { "error": "<message>", "code"? }. |
2026-11-01 | エラーにはエンベロープが使用されます { "error": { code, message, details?, requestId, retryable, docUrl } }. |
RTCでは、お客様から送信された日付より新しいものではない最新バージョンを適用し、 それを RTC-Version レスポンスヘッダー。最初の バージョンより前の日付のものは、元のシェイプを維持します。コードが 基づいているバージョンを固定し、アップグレードする際に意図的に変更してください。
Webhookのペイロードを固定するには、 apiVersion
Section titled “Webhookのペイロードを固定するには、 apiVersion”各 Webhookエンドポイント には apiVersion これは、 リクエストヘッダーとは無関係に、受信したエンベロープを修正するものです:
apiVersion | エンベロープ |
|---|---|
legacy | { id, type, createdAt, projectId, data }、以前の単一のWebhookはエンドポイントに移行されました |
2026-11-01 | { id, type, apiVersion, createdAt, tenantId, projectId, roomId?, data }、新しいエンドポイントのデフォルト設定です |
イベント data は、と同様に追加的に拡張されますAPI。受信者を新しい ペイロードバージョンに移行するには、新しいバージョンを指定した 2 つ目のエンドポイントを追加し、 処理を切り替えた後、古いエンドポイントを削除してください。
契約バージョン: SDKs
Section titled “契約バージョン: SDKs”GET /v1/capabilities レポート contractVersion、これは カスタマー契約に何かが追加されるたびに変更されます。 はこれを利用して、 APIがすでにAPIサポートしている場合に限り、新しい機能を有効にSDKsすることができます。
OpenAPI 記述
Section titled “OpenAPI 記述”RTCの顧客ルートはOpenAPI 3.1で記述されており、 リクエストの検証APIに使用されるスキーマから生成され、変更のたびに コードと照合されています。このファイルは docs/openapi/v1.yaml RTC プラットフォームのリポジトリにあります。 お問い合わせ CHAMPREP へ クライアント生成用の現在のファイルを受け取ります。この参照と
API 参照 は公開ドキュメントのままとなります。