RESTful API 規範


分類

建立時間: 2024年7月8日 08:31
更新時間: 2024年7月8日 09:10

說明

本篇將分享我所遵守的 RESTful API 規範有哪些。

回傳格式

我統一回傳 Json 格式,無論成功或是失敗。

回傳內容

我這裡只簡單描述一些規範,完整內容請參考連結 JSend

回傳的鍵值使用小駝峰式命名法(lower camel case),這是普遍常見的命名法,如果使用其他種命名法,可能要處理別處取得資料的鍵名,因為別處很有可能也是使用小寫駝峰。

回傳的內容固定三個:

  • data: 把要回應的資料統一放在 data 裡面。
  • message: 回應訊息。
  • status: 回應狀態。

不一定要每個鍵值都存在,看情況調整,例如: status 一定要有,message 可以不填。

成功

{
    "data": {
        "posts": [
            {
                "id": 1,
                "title": "A blog post",
                "body": "Some useful content"

            },
            {
                "id": 2,
                "title": "Another blog post",
                "body": "More content"
            }
        ]
    },
    "message": "Respnse message.",
    "status": "success"
}

失敗

{
    "data": {
        "title": "A title is required"
    },
    "message": "Respnse message.",
    "status": "fail"
}

回應狀態碼

無論你有任何安全性的考量,建議在每一個 API 回應正確的狀態碼,然後在中介層統一處理,或者你有其他更好的辦法也行,只要不要寫死在每個 API 就好, 因為當你真的要使用正確的狀態碼時,你會改得很辛苦。

狀態碼不單純只是被用來前後端溝通,它還可以來監控伺服器狀況。

回應狀態碼有非常多,最基本要知道狀態碼是如何分類:

  • 2xx: 成功
  • 3xx: 轉址
  • 4xx: 使用者端錯誤
  • 5xx: 伺服器端錯誤

參考

觀看次數: 54
apijsonrestful
按讚追蹤 Enjoy 軟體 Facebook 粉絲專頁
每週分享資訊技術

一杯咖啡的力量,勝過千言萬語的感謝。

支持我一杯咖啡,讓我繼續創作優質內容,與您分享更多知識與樂趣!