RESTful API 規範

說明

本篇將分享我所遵守的 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: 伺服器端錯誤

參考

• JSend