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