記述と実施を区別する
ツールが対応する仕様版を固定し、パラメーター、本文、応答、セキュリティ要件を記述します。宣言した要件は、アプリケーションやゲートウェイが実際に強制する必要があります。
| 要素 | 記述する内容 | 追加の確認 |
|---|---|---|
| スキーマ | 構造と制約 | 実際の検証と業務ルール。 |
| 文書化した応答 | 期待する状態と内容 | 実応答との一致。 |
| セキュリティ要件 | 宣言した方式と権限 | 操作ごとの実際のアクセス制御。 |
| 例 | 一つの参考事例 | 整合性、秘密の除去、境界事例。 |
共有前に見直す
- 必須項目、型、範囲、ページ分割、エラー、内容形式を確認します。秘密や顧客データを使わず、スキーマに合う架空例を示します。
- 管理された環境で記述と実際の送受信を比較します。認証情報なし、権限不足、アカウント間の分離を試験します。
- 外部参照と、それを読み込むツールを確認します。公開記述から機密を除き、非公開環境や操作を保護します。
文書を継続的に保守する
変更差分を確認し、担当者を決めます。生成されたクライアントや例は構造が正しくても業務ルールを見落とし得ます。対話型コンソールには適切な環境、限定権限、状態を変える操作の明示が必要です。
一次資料
OpenAPIと実行中のサービスを比較してください。
有用なOpenAPIの説明には、失敗時の応答、スキーマ、クライアントが実際に遭遇する例が含まれています。ドキュメントとAPIが乖離している場合、デモでは成功しても、本番環境では失敗する可能性があります。
- 成功ケースとエラーケースを説明と比較してください。
- オプション値、ページネーション、操作制限を文書化してください。
- 契約を変更する前に、代表的なクライアントでテストしてください。
一次資料：IETF RFC 9457 — Problem Details for HTTP APIs. 関連する方法：実践ガイドを読む.
ZIPとTAR：保存先と資源の範囲内で展開する
展開したファイルを公開する前にパス、リンク、展開量を検証します。
- 最小権限の新しい非公開フォルダーに展開します。絶対パス、親への移動、不要なリンクや特殊ファイルを拒否します。実際に解決した保存先と名前衝突を、大文字小文字も含む対象システムの規則で確認します。文字列の前方一致だけでは隔離を証明できません。
- 書き込んだバイト数、項目数、深さ、時間、プロセス資源に個別・合計制限を設けます。圧縮サイズや申告サイズだけに頼りません。不要な入れ子を拒否し、許可時は全階層で予算を共有します。ライブラリーとフィルターを更新します。
- ../、絶対パス、リンク、重複、予算超過を試します。途中停止で公開されず既存ファイルも置換されないことを確認します。型と内容を検証後に公開し、削除時は隔離フォルダーの保存先を確認します。
再現できる受け入れ事例
架空の例です。顧客や実際の観測結果を示すデータではありません。
事例の入力を見る
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}期待される判断
架空例：2 MBの圧縮データが600 MBに展開され、予算は100 MBです。実際の書き込み量超過で停止し、初期ファイルが正常でも公開しません。
Python — tarfile extraction filters and further verification
小さなアーカイブやフィルターは安全を保証しますか？
いいえ。大きく展開する場合があります。資源制限、パス規則、出力ファイル確認を加えます。
一次資料：Python — tarfile extraction filters and further verification. 関連する方法：実践ガイドを読む.
APIエラー：型・状態・証拠
この言語版の詳しい参照メモは英語で提供しています。
Include errors in contract tests
A new type URI, removed extension or changed status may alter consumer behaviour. Failure examples are part of the contract alongside successful responses.
- Replay existing clients against representative refusals.
- Check tolerance of unknown extensions and localised text.
- Document migration of a problem identity and actually observed use.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5