[ADP-129] Expect

注意！

經過進一步研究，我們發現 Expect 標頭及其相關的狀態碼無關乎一般的 API 設計。為了更靈活的請求處理，我們建議改用 Prefer 標頭（請參閱 ADP-136）。

概述

Expect HTTP 標頭由客戶端使用，用於指示服務器應如何處理請求的某些期望。此標頭的主要用途是在發送請求主體之前，告知服務器客戶端期望收到 100-continue 回應。本指南概述了在我們的 API 中如何以及何時使用 Expect 標頭。

Expect 標頭的使用

1. 目的:

   • Expect 標頭主要用於避免在不確定服務器是否會接受請求的情況下向服務器發送大型請求主體。通過使用 Expect: 100-continue 標頭，客戶端要求服務器在客戶端發送請求主體之前驗證它是否可以處理該請求。

2. 語法:

   • 標頭應按以下格式使用：

     Expect: 100-continue

3. 使用時機:

   • 在發送大型負載（如文件上傳）時使用 Expect 標頭，以最小化發送最終會被服務器拒絕的數據的風險。
   • 在網絡帶寬有限或發送大量數據成本高昂的情況下特別有用。

4. 服務器行為:

   • 收到帶有 Expect: 100-continue 標頭的請求時，服務器應：
     1. 如果準備好接收請求主體，則回應 100 Continue 狀態碼。
     2. 如果無法按預期處理請求，則回應最終狀態碼（例如 417 Expectation Failed、4xx 或 5xx 錯誤）。

5. 客戶端行為:

   • 客戶端應：
     1. 在發送請求主體之前等待 100 Continue 回應。
     2. 如果服務器回應 417 Expectation Failed 或任何其他錯誤狀態，客戶端不應發送請求主體。
     3. 根據服務器的回應適當處理任何錯誤。

6. 錯誤回應:

   • 所有錯誤回應都應符合 HTTP Problem (RFC 9457) 規範，參見 ADP-401: HTTP問題基礎。

示例

客戶端請求:

POST /upload HTTP/1.1
Host: api.example.com
Content-Length: 10485760
Expect: 100-continue
Content-Type: application/octet-stream
[尚未發送請求主體]

服務器回應:

HTTP/1.1 100 Continue

客戶端動作:

• 收到 100 Continue 後，客戶端繼續發送請求主體。

服務器回應（如果服務器無法處理請求）:

HTTP/1.1 417 Expectation Failed
Content-Type: application/problem+json
Content-Lauguage: zh-tw
{
  "type": "https://example.com/probs/cannot-process",
  "title": "Expectation Failed",
  "status": 417,
  "detail": "服務器當前無法處理此大小的上傳請求",
  "instance": "/upload/1234"
}

客戶端行為:

• 收到 417 Expectation Failed 錯誤回應後，客戶端中止請求，不發送請求體，並根據錯誤詳情採取適當行動。

參考

• https://www.rfc-editor.org/rfc/rfc9110#field.expect
• https://www.rfc-editor.org/rfc/rfc9457

Changelog

• 2025.01.16: Retiring this for API design