Blog 265/365：【學新知】API動詞規則與命名

🤔為什麼要寫這篇小記？

今天在公司討論新需求的流程時，Frontend developer建議可以用既有流程圖為基礎，在圖上加上每個步驟可能會需要用到的API。

這對我真的是一項挑戰，畢竟我對公司內部的API完全不熟悉呀！不過既然是一個練習機會，那就嘗試看看吧。

我在開始設計API流程圖時碰到的問題如下：
  • 如何判斷這個畫面使用到API？
  • API應該怎麼命名？

最後我在Google上的一篇文章《API 實作(一)：規劃 RESTful API 要注意什麼
》找到了答案，讓我對Restful API有更多的了解。

🤔如何判斷這個畫面使用到API？

初步構想到的規則是，「只要這個步驟需要資料進行判斷」，有很大的機率就需要API。例如說：
  • User 登入/註冊：前端需要API去查詢User是否存在於現在的DB、前端需要API將User填寫的資訊寫到DB中
    • 通常設計會用 (Get) /auth、(POST) / user
  • 呈現某些資訊：前端要呈現某些資訊，例如帳戶餘額

🤔API應該怎麼命名？

初步首先要了解近期Restful API的命名規則為「動詞 + 名詞」。動詞主要有以下五種：
  • POST：新增
  • GET：讀取
  • PUT：修改（修改整份文件）
  • PATCH：修改（修改其中幾個欄位）
  • DELETE：刪除

在名詞方面，Endpoints 可以說是 RESTful 的「名詞」。原則上這些名詞不使用大寫，若是由多個字組成，通常會使用底線（_）隔開。例如：
  • 新增使用者：POST /user
  • 查所有帳號：GET /users
  • 查詢使用者：GET /user/1
  • 修改使用者：PUT /user/1
  • 刪除使用者：DELETE /user/1

🤔補充：API Status Code

除了了解 HTTP Method 以外，也應該稍微了解API HTTP Status Code 來表達回應狀態。原則上成功的話使用 2XX、失敗看情況，如果是使用者做錯就使用 4XX、伺服器出錯就使用 5XX，以下是幾個常用的狀態：

  • 200 OK：成功。通常用在查詢（GET）的部分。
  • 201 Created：資源新增成功。通常用在新增（POST）的部分。
  • 202 Accepted：請求已接受，但還在處理中。（換句話說可能失敗）
  • 204 No Content：請求成功，沒有返回內容。通常我用在刪除（DELETE）或修改（PUT）的部分。也有人會把修改成功放在 201。
  • 400 Bad Request：使用者做錯的通用狀態。通常我用在有必填欄位未填或資料錯誤的狀況。
  • 401 Unauthorized：使用者沒有進行驗證。
  • 403 Forbidden：使用者已經登入，但沒有權限進行操作。
  • 404 Not Found：請求的資源不存在。
  • 410 Gone：資源已經過期。
  • 500 Internal Server Error：伺服器端錯誤。
  • 502 Bad Gateway：通常是伺服器的某個服務沒有正確執行。
  • 503 Service Unavailable：伺服器臨時維護或是快掛了，暫時無法處理請求。
  • 504 Gateway Timeout：伺服器上的服務沒有回應。