ポリシー
alphaアクセス、エラー、安定性、データ保持。
このページでは /api/v1alpha1 DeepFrame API に適用されるポリシーを説明します。
Alphaアクセス
Public API Alpha（DeepFrame API向けのalpha keyタイプ）はオプトイン方式のsurfaceです。プラットフォーム管理者がワークスペースでこれを明示的に有効にするまで、APIはalphaトラフィックを許可しません。リクエストには、ルートアクセス権限を持つ、このタイプの有効なAPIキーも必要です。Standard APIキーではalphaルートを呼び出せません。
APIキーが有効でもワークスペースがオプトインしていない場合、APIは403の forbidden problemを返します。alphaアクセス権限のないキーは、引き続き404の resource-not-found になります。これらのレスポンスは application/problem+json です。
エラーカタログとリトライ可否
/api/v1alpha1 のすべてのエラーは application/problem+json を使用し、type、title、status、detail、instance、request_id を含みます。type URIが安定したエラーコントラクトです。detailの文面は変更される場合があります。
| Status | カタログの概要 | リトライの指針 |
|---|---|---|
| 400 | bad-request、validation-error、invalid-cursor、ssrf-blocked | いいえ。リクエストを修正するか、新しいカーソルまたはURLを使います。 |
| 401 | unauthorized | いいえ。キーを修正または交換します。 |
| 402 | quota-exceeded | いいえ。クォータまたはプランが変わるまで待ちます。 |
| 403 | forbidden。ワークスペースのalphaオプトイン拒否を含みます。 | いいえ。権限、課金状態、トライアル状態、またはワークスペースのオプトインを修正します。 |
| 404 | resource-not-found | いいえ。リソース、ワークスペース、キーのalphaアクセスを確認します。 |
| 409 | conflict または idempotency-in-flight | リソースの状態が変わった後だけです。idempotency-in-flight は待って同じペイロードをリトライします。 |
| 422 | unprocessable-entity または idempotency-payload-mismatch | いいえ。入力を修正するか、同じキーで元のペイロードを使います。 |
| 429 | rate-limit-exceeded | はい。リトライ前に Retry-After と X-RateLimit-* ヘッダーに従います。 |
| 500 | internal-error | 操作がべき等で安全に再実行できる場合だけです。 |
| 503 | service-unavailable | はい。上限付きの指数バックオフとジッターを使います。 |
分岐には detail やstatusだけでなく、type URIを使ってください。429以外の4xxは、リクエストまたは状態を変更せずにリトライしないでください。
Alphaの安定性
/api/v1alpha1 はalphaチャネルです。このalphaリビジョンでは互換性を保証しません。破壊的変更は /api/v1alpha2 として提供され、旧alphaリビジョンには Deprecation および Sunset ヘッダーによる30日間の廃止期間が設定される場合があります。
APIリファレンスとレスポンスの動作は、同じOpenAPIコントラクトから生成されます。Deprecation と Sunset が現れた場合はログに記録してください。
データ保持
保存されたprofile、report template、分析ラン（Run）は、削除ではなくアーカイブ（archive-not-delete）で保持します。profileとreport templateのversionは追記専用です。headをアーカイブすると新しい分析ラン（Run）は開始できず、通常の一覧から非表示になりますが、すべてのversionは保持され、過去の分析ラン（Run）、answer、reportは生成元の正確なversionを解決できます。
テナントのオフボーディングによるpurgeは、別のオーナー承認操作です。alphaの DELETE 呼び出しでは実行されず、リソースのアーカイブから推測してはいけません。