HTTP 方法與狀態碼 — 讓 API 說人話

用使用者資料 API 對照 GET、POST、PUT、PATCH、DELETE 的語意與冪等性,再整理成功、重新導向和錯誤狀態碼的用法。

本篇目錄

設計或串接 API 時,經常會用到 HTTP 方法(Methods)和狀態碼(Status Codes)。方法說明要做什麼,狀態碼則告訴呼叫端處理結果。用法一致,雙方就比較容易理解彼此的請求與回應,後續也好維護。

HTTP 方法:動作是什麼?

常見的資源 API 可以用 CRUD 來理解,但 HTTP 方法描述的是資源操作,不一定直接對應一條資料庫指令。下面先用使用者資料當例子:

GET:讀取資料

  • 用途:取得資源。
  • 特性:安全(Safe)且冪等(Idempotent)。意思是呼叫端只要求讀取資料,重複呼叫也不應額外改變資源狀態。伺服器仍可能寫入存取紀錄,而資料更新後,兩次查詢的回應也可能不同。
  • 例子:GET /users/123(取得 ID 為 123 的使用者資料)

POST:新增資料

  • 用途:提交資料供資源處理,常見情境是建立新資源,也可以用在執行操作。
  • 特性:預設不保證冪等。重複送出可能建立兩筆資料;如果 API 設計了防重複機制,就能避免。
  • 例子:POST /users(建立一個新使用者)

PUT:更新資料(整筆替換)

  • 用途:用請求中的表示替換目標資源;API 允許時,也可以在指定網址建立原本不存在的資源。
  • 特性:冪等。
  • 例子:PUT /users/123(用新的完整資料替換使用者 123 的資源表示;哪些欄位必填、省略時如何處理,要看 API 的規則)

PATCH:更新資料(部分修改)

  • 用途:只修改部分欄位。
  • 特性:不保證冪等,要看修改內容。把 email 設成指定值可以是冪等的;每次把點數加 1 就不是。
  • 例子:PATCH /users/123(只修改使用者 123 的 email)

DELETE:刪除資料

  • 用途:移除資源。
  • 特性:冪等。刪除一次或多次,預期效果都是資源被移除,但每次回傳的狀態碼不一定相同。
  • 例子:DELETE /users/123(刪除使用者 123)

HTTP 狀態碼:結果如何?

狀態碼分為五大類:

1xx:資訊回應

  • 100 Continue:伺服器已收到請求的標頭,客戶端應繼續發送主體。

2xx:成功(Success)

  • 200 OK:最常見的成功回應。
  • 201 Created:請求成功且建立了新資源。通常用於 POST 請求的回應。
  • 204 No Content:請求成功,但回應沒有內容。通常用於 DELETE 請求。

3xx:重新導向(Redirection)

  • 301 Moved Permanently:資源已永久移動到新位置。搜尋引擎會更新索引。
  • 302 Found:資源暫時移動到新位置。
  • 304 Not Modified:客戶端帶著快取的驗證資訊詢問,伺服器確認資源沒有變更,因此可以沿用快取。這也可能發生在快取已過期、需要重新確認的時候。

4xx:客戶端錯誤(Client Error)

  • 400 Bad Request:請求格式錯誤,伺服器看不懂。
  • 401 Unauthorized:未認證。你沒有登入或 Token 無效。
  • 403 Forbidden:伺服器拒絕存取。常見原因是權限不足,但不代表使用者一定已登入。
  • 404 Not Found:找不到資源,或伺服器選擇不透露它是否存在。
  • 418 I’m a teapot:典故來自愚人節的茶壺協定,意思是「你不能用茶壺來泡咖啡」,偶爾會出現在彩蛋裡。現行 RFC 9110 將它列為保留的 (Unused),一般 API 不要拿它代替正式定義的錯誤狀態。
  • 429 Too Many Requests:請求次數過多,被限流了。

5xx:伺服器錯誤(Server Error)

  • 500 Internal Server Error:伺服器壞了,或是程式碼噴錯了。通常是後端要修這個 bug。
  • 502 Bad Gateway:作為閘道或代理的伺服器,從上游伺服器收到無效回應。常見於 Nginx 設定錯誤。
  • 503 Service Unavailable:伺服器暫時無法處理請求(過載或維護中)。
  • 504 Gateway Timeout:閘道等不到上游伺服器的回應。

為什麼要區分這麼細?

其實你可以永遠都回傳 200 OK,然後在 JSON 裡用 success: false 來表示錯誤。但這樣做有幾個缺點:

  1. 監控容易漏看錯誤:如果監控只依 HTTP 狀態碼判斷成功與否,全部回 200 就會把失敗也算成成功。
  2. 不符合語意:瀏覽器和快取伺服器依賴狀態碼來決定行為(例如看到 304 就讀快取)。
  3. 溝通成本高:串接方需要去讀你的文件才知道 error_code: 999 是什麼意思,而不像 404 是通用語言。

這些用法可查 HTTP 語意規範 RFC 9110。遇到不熟的狀態碼時,我會先確認它的定義,再對照 API 的實際行為。

結語

可以把 HTTP 方法想成動詞、URL 想成名詞,狀態碼則交代結果。設計 API 時把這些資訊表達清楚,串接的人就知道該怎麼呼叫,收到回應後又該怎麼處理。


站內相關文章: