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 來表示錯誤。但這樣做有幾個缺點:
- 監控容易漏看錯誤:如果監控只依 HTTP 狀態碼判斷成功與否,全部回 200 就會把失敗也算成成功。
- 不符合語意:瀏覽器和快取伺服器依賴狀態碼來決定行為(例如看到 304 就讀快取)。
- 溝通成本高:串接方需要去讀你的文件才知道
error_code: 999是什麼意思,而不像404是通用語言。
這些用法可查 HTTP 語意規範 RFC 9110。遇到不熟的狀態碼時,我會先確認它的定義,再對照 API 的實際行為。
結語
可以把 HTTP 方法想成動詞、URL 想成名詞,狀態碼則交代結果。設計 API 時把這些資訊表達清楚,串接的人就知道該怎麼呼叫,收到回應後又該怎麼處理。
站內相關文章: