API 規(guī)范

1. 基本約定

• 以 dingo api 錯誤返回為基礎(chǔ)，如果有不確定的請以文檔為準(zhǔn)。
• 正常返回數(shù)據(jù)的情況：

1. 不包含 status_code 信息
2. http code 數(shù)值區(qū)間在 200 - 300 之間。
3. 數(shù)據(jù)額外信息，需要放到 `meta` 里面。

• 數(shù)據(jù)異常的情況：

1. http code 碼為對應(yīng)錯誤碼。
2. 需要包含 status_code (一般和 http code 碼一致),  message (錯誤提示)
3. 具體詳細(xì)錯誤返回，請放到 `errors` 里面。

2. 標(biāo)準(zhǔn)路由示例

GET /issues                                      列出所有的 issue
GET /orgs/:org/issues                            列出某個項目的 issue
GET /repos/:owner/:repo/issues/:number           獲取某個項目的某個 issue
POST /repos/:owner/:repo/issues                  為某個項目創(chuàng)建 issue
PATCH /repos/:owner/:repo/issues/:number         修改某個 issue
PUT /repos/:owner/:repo/issues/:number/lock      鎖住某個 issue
DELETE /repos/:owner/:repo/issues/:number/lock   解鎖某個 issue

2. 對于錯誤數(shù)據(jù)，默認(rèn)使用 dingo 的錯誤格式， 如下結(jié)構(gòu)：

'message' => ':message',          // 錯誤的具體描述
'errors' => ':errors',            // 參數(shù)的具體錯誤描述，422 等狀態(tài)提供，（此項非必需）
'status_code' => ':status_code',  // http狀態(tài)碼
'debug' => ':debug',              // debug 信息，非生產(chǎn)環(huán)境提供

-  舉個例子：
{
    "message": "Could not create new user.",
    "status_code": 422,
}

• 下面是通用的資源異常的列表，它們都會返回 HTTP 422 狀態(tài)碼。參考

Dingo\Api\Exception\DeleteResourceFailedException
Dingo\Api\Exception\ResourceException
Dingo\Api\Exception\StoreResourceFailedException
Dingo\Api\Exception\UpdateResourceFailedException

**如果需要展示詳細(xì)錯誤，請勿放到 'message' 里， 參考： **

  if ($validator->fails()) {
            throw new Dingo\Api\Exception\StoreResourceFailedException('Could not create new user.', $validator->errors());
        }
- 返回數(shù)據(jù)格式：
{
    "message": "Could not create new user.",
    "status_code": 422,
    "errors": {
        "username": [
            "The username field is required."
        ],
        "password": [
            "The password field is required."
        ]
    }
}

• 常用異常參考：