画像変換API:受付から結果を確かめるまで
全体像
これは画像変換を受け付けて後から結果を確かめる、提供された架空APIの説明です。サーバーの202は受付であり、クライアントが結果を表示できる完了状態とは別です。
受付と処理の完了を分ける理由
サーバーは画像変換の終了を待たずに202とjobIdを返します。クライアントは返されたjobIdで保存済みの状態を読み、変換の結果を判断します。202だけを受け取って結果表示へ進むと、クライアントは未完了のジョブを完了と誤認します。
実際の値を使う通信例へ。API固有の規則は提供された架空仕様です。HTTPの202も処理の受付と未完了を表します(RFC 9110 §15.3.3)。
この例が決めていない運用条件
架空仕様は認証、画像アップロード、保存先の実装、キューの方式、排他制御、削除、保持期間を定めていません。図の保存先は状態を保持する役割であり、特定のデータベース製品を要求しません。
通信を追う
同じ依頼を再送するとき、クライアントは同じrequestKeyを使います。サーバーは同じjobIdを返すため、再送によって重複ジョブを作りません。
番号付き解説を順に確認できます。再生の時間は処理時間を示しません。
同じ依頼では同じrequestKeyを保つ
クライアントが再送でrequestKeyを作り直すと、同一キーの保証の前提を満たしません。次の通信例は、図の①に対応するimg_42とreq_Aの初回受付です。
POST /jobsContent-Type: application/json{"imageId":"img_42","requestKey":"req_A"}202 Accepted{"jobId":"job_17"}
上の応答は受付の結果です。クライアントは202を受け取っても画像を表示せず、次にjob_17の状態と結果を読みます。GET応答のJSONに使うstatusフィールドとURLの具体値は説明用で、提供仕様にJSONの完全な形式はありません。
2回目のPOSTと、未定義のキー条件
クライアントが同じ画像とreq_Aを再送すると、サーバーは重複ジョブを作らずjob_17を返します。架空仕様は同じキーで異なる画像を送る場合、キーの有効期限、並行したPOSTの実装方法、再送時のHTTP応答ステータスを定めていません。利用者は同じキーなら異なる依頼も安全にまとめられるとは解釈できません。
状態と結果
状態はjob_17という同じジョブの進行を表します。ワーカーが状態と結果を保存し、クライアントはGETの値を読んで結果または失敗理由を表示します。
GETの値が表示を決める
次の通信例では、クライアントが最初にqueuedを読み、後の照会でcompletedとresultUrlを読みます。実際に何回照会するかを決めるGETの間隔と打ち切り条件は、架空仕様にありません。
GET /jobs/job_17{"status":"queued"}GET /jobs/job_17{"status":"completed","resultUrl":"https://example.invalid/results/job_17.png"}
失敗側の通信例と、模擬実行の全状態
GET /jobs/job_17{"status":"failed", "reason":"画像を変換できませんでした"}
ワーカーの成功と失敗は同じジョブの代替結果です。この説明ではcompletedの後にfailedへ遷移しません。failedからqueuedへの自動再実行も仕様にありません。
インメモリ模擬実行の全出力には、同じjob_17のqueued、running、成功終端と、別試行の失敗終端を保存しました。
再送と停止
クライアントがPOSTの503を受けたときだけ、提供仕様の再試行規則を使います。初回+最大2回の追加送信でも503なら、クライアントは受付結果不明と表示します。
追加2回は、合計3送信まで
図の①〜③を同じキーで試し、応答がすべて503になる例です。クライアントは追加送信を2回に抑え、4回目を送信しません。
1回目 POST /jobs requestKey=req_A → 5032回目 POST /jobs requestKey=req_A → 5033回目 POST /jobs requestKey=req_A → 503クライアント表示: 受付結果不明
「受付結果不明」はジョブのfailed状態とは異なります。failedはワーカーが保存した変換の失敗であり、受付結果不明はクライアントが受付を確定できない表示です。クライアントは不明を画像変換失敗へ置き換えません。
HTTP一般の意味と、この架空APIだけの再試行規則
HTTPの503はサーバーが一時的に要求を扱えない応答です。サーバーはRetry-Afterで待ち時間を示せますが、この架空APIは待ち時間やバックオフを定めていません。同じrequestKeyを使う規則と追加2回の上限は提供仕様だけの規則です(RFC 9110 §15.6.4、架空仕様)。
503以外のPOST応答、通信断、タイムアウト、GETの失敗時は未定義です。この説明は未定義の条件へ再試行規則を拡張しません。
資料と確認範囲
API固有の規則は提供された架空仕様です。HTTP一般の資料と説明用の仮定を分けて確認できます。
このページは資料名と確認範囲を示します。原文・HTTP資料・模擬実行の説明へ。
説明の根拠を分ける
job_17、requestKey、状態、最大2回という規則は提供された架空仕様に基づきます。RFCはHTTPの意味を確認する補助資料であり、この架空APIの存在や動作を保証しません。
- RFC 9110 §15.3.3:202の受付と未完了。
- RFC 9110 §15.6.4:503と任意のRetry-After。
- 提供仕様と説明先の照合表。
- 4論理図の専任担当と標準成果物。各図の担当は一次資料を実閲覧し、調査・設計・図・対応解説・表示確認を保存しました。
制作者はインメモリ模擬実装を node simulation.cjs で実行しました。模擬結果は入力の説明との整合を確かめるためのものです。模擬実装が再送にも202を返す点は説明用の仮定です。原文は再送のHTTP状態を定めていません。実APIへの通信、永続化、並行アクセスの保証や利用者による承認は実施していません。
原文と模擬コードの全文
原文はinput.mdへ保存しました。模擬コードは架空仕様の説明用です。
// 説明用のインメモリ模擬実装。実APIへの通信ではない。// 再送応答の202は模擬実装の仮定。原文は再送時のHTTP状態を指定しない。const jobs = new Map();let nextId = 17;function post({imageId,requestKey}) {if (!jobs.has(requestKey)) jobs.set(requestKey,{jobId:`job_${nextId++}`,imageId,status:'queued'});return {status:202,body:{jobId:jobs.get(requestKey).jobId}};}function get(jobId) { return {...[...jobs.values()].find(j=>j.jobId===jobId)}; }function run(jobId,success) {const job=[...jobs.values()].find(j=>j.jobId===jobId);job.status='running';const running=get(jobId);if(success){job.status='completed';job.resultUrl='https://example.invalid/results/job_17.png';}else {job.status='failed';job.reason='画像を変換できませんでした';}return {running,terminal:get(jobId)};}function retry(statuses,requestKey='req_A') {const sent=[];for(let i=0;i<3;i++){const status=statuses[i];sent.push({attempt:i+1,requestKey,status});if(status===202)return {sent,display:'受付済み。job_17の状態を取得する'};if(status!==503)throw new Error('この模擬例が扱わない応答');}return {sent,display:'受付結果不明'};}const input={imageId:'img_42',requestKey:'req_A'};const first=post(input),duplicate=post(input),queued=get('job_17');const success=run('job_17',true);jobs.clear();nextId=17;post(input);const failure=run('job_17',false);const result={notice:'提供された架空仕様の理解を助ける模擬実装であり、実サーバー、永続化、排他制御の実装保証ではない。',input,first,duplicate,queued,success,failure,retries:[[202],[503,202],[503,503,202],[503,503,503]].map(s=>retry(s)),unspecified:['再送時のHTTP応答状態','キーの有効期間','同じキーで異なる画像IDの場合','並行POSTの排他','GETの間隔','503の待ち時間・バックオフ','POST以外のエラー応答']};require('node:fs').writeFileSync(require('node:path').join(__dirname,'simulation-results.json'),JSON.stringify(result,null,2)+'\n');console.log(JSON.stringify({first:first.body.jobId,duplicate:duplicate.body.jobId,queued:queued.status,completed:success.terminal.status,failed:failure.terminal.status,retryCounts:result.retries.map(r=>r.sent.length)}));