APIの安定性、バージョニング、非推奨ポリシー
RealityConnect APIを長期的な基盤として利用する前に、どの部分が安定しているか、実験的な操作がどのようにマークされているか、アップグレードのたびに何を確認すべきかを理解してください。
実験的な操作
Section titled “実験的な操作”APIリファレンスの一部の操作には、実験的な安定性マーカーが付いています。OpenAPIドキュメント上で操作に x-scalar-stability: experimental が付いているか（レンダリングされたAPIリファレンスでは安定性バッジとして表示されます）で見分けてください。これはAPIと自動的に同期されるため、ここに固定リストを載せるよりも、そちらを確認する方が確実です。
実験的な操作は無効化されたものやプレビュー専用ではなく、実際に呼び出せる操作です。ただし、パス、パラメータ、ペイロード、レスポンス、可用性が、APIの他の部分と同じ安定性保証なしに変更される可能性があります。実験的な操作の扱い方については、実験的エンドポイントを参照してください。
実験的な操作が安定版になった場合は、リリースノートで告知されます。
破壊的変更と非破壊的変更
Section titled “破壊的変更と非破壊的変更”| 変更 | 破壊的か | 理由 |
|---|---|---|
| 新しいオプションのリクエストパラメータ | いいえ | 既存のリクエストは変更なく動作し続ける |
| 新しいレスポンスフィールド | いいえ | 既知のフィールドのみを読む既存クライアントは影響を受けない。レスポンスは寛容にパースし、未知のフィールドは無視すること |
| 既存フィールドへの新しいenum値の追加 | いいえ | enumフィールドはオープンな集合として扱い、既知の値を網羅的に照合するのではなく未知の値も適切に処理すること |
| 既存フィールドの削除または名称変更 | はい | そのフィールドを読むクライアントを壊す |
| 既存フィールドの型や意味の変更 | はい | 以前の形式に依存するクライアントを壊す |
| 既存操作への必須パラメータの追加 | はい | それを送らない既存のリクエストを壊す |
| エンドポイントのパスまたはHTTPメソッドの変更 | はい | 既存のリクエストを完全に壊す |
| 実験的な操作の契約が変わる | いいえ（意図的） | 実験的な操作は明示的に安定性契約の対象外（上記を参照） |
非推奨ポリシー
Section titled “非推奨ポリシー”安定した操作は、削除される前にサンセット日付きで非推奨になります。APIリファレンスではその操作が非推奨として表示され、OpenAPI定義には deprecated: true と、x-sunset にサンセット日（YYYY-MM-DD）が含まれます。
- 非推奨になった安定した操作はサンセット日まで引き続き動作し、その日以降に削除される場合があります。
- 固定の最低告知期間はありません。各非推奨化のサンセット日がその告知となります。
- サンセット日付きで非推奨になったリクエストパラメーターも同じルールに従います。
- 一部のクエリパラメーターは後方互換のエイリアス付きで名前が変更されます。古い名前は新しい名前と並行して引き続き動作します。
- 実験的な操作は対象外です。上記の実験的な操作のとおり、サンセット日なしで非推奨になったり、告知なしに変更または削除されたりする場合があります。