>[info]遵循統一的REST 的設計風格，使用JSON作為數據交互的格式。
## **數據格式**
使用`JSON`作為消息體的數據交換格式。請求須設置HTTP頭部：
```
Content-Type: application/json
Accept: application/json
```
>[danger]文件上傳API除外。
## **HTTP動詞**
對于資源的具體操作類型，由HTTP動詞表示：
* `GET`：從服務端取出資源（一項或多項）。
* `POST`：在服務端新建一個資源。
* `PUT`：在服務端更新資源（客戶端提供改變后的完整資源）。
* `PATCH`：在服務端更新資源（客戶端提供改變的屬性）。
* `DELETE`：從服務端刪除資源。
## **HTTP狀態碼**
常見的HTTP狀態碼見下表：
| 狀態碼 | 描述| 典型錯誤碼示例 |
|---|---|---|
| 200 - OK | 請求成功 | / |
| 201 - Created | 新建或修改數據成功 | / |
| 204 - No Content| 刪除數據成功 | / |
| 400 - Bad Request | 客戶端錯誤 | CLIENT_ERROR |
| 401 - Unauthorized | 令牌、用戶名、密碼錯誤 | TOKEN\_INVALID |
| 403 - Forbidden | 權限異常 | NO_AUTH |
| 422 - Unprocesable Entity | 參數非法 | PARAM_ERROR |
| 500 - Internal Server Error | 服務端錯誤 | SERVER_ERROR |
## **返回結果**
針對不同操作，服務端向用戶返回的結果應該符合以下規范：
* `GET /collection`：返回資源對象的列表（數組）
* `GET /collection/resource`：返回單個資源對象
* `POST /collection`：返回新生成的資源對象
* `PUT /collection/resource`：返回完整的資源對象
* `PATCH /collection/resource`：返回完整的資源對象
* `DELETE /collection/resource`：返回一個空文檔
## **錯誤信息**
當請求處理失敗時，除了HTTP狀態碼表示錯誤之外，API將在消息體返回錯誤相應說明具體的錯誤原因：
* `code`：詳細錯誤碼
* `message`：錯誤描述，使用易理解的文字表示錯誤的原因
* `issue`：具體錯誤原因
* `file`：報錯文件路徑
* `line`：報錯文件行數
```
{
"code": "SERVER_ERROR",
"message": "服務端錯誤",
"detail": {
"file": "E:\Back End Project\kirin-bdf\app\portal\controller\TestController.php",
"line": 8,
"issue": "未定義變量: foo"
}
}
```
>[danger]生產環境下，不會返回detail。
