2022-07-16

API 规范

1. 基本约定

• 以 dingo api 错误返回为基础，如果有不确定的请以文档为准。
• 正常返回数据的情况：

1. 不包含 status_code 信息
2. http code 数值区间在 200 - 300 之间。
3. 数据额外信息，需要放到 `meta` 里面。

• 数据异常的情况：

1. http code 码为对应错误码。
2. 需要包含 status_code (一般和 http code 码一致),  message (错误提示)
3. 具体详细错误返回，请放到 `errors` 里面。

2. 标准路由示例

GET /issues                                      列出所有的 issue
GET /orgs/:org/issues                            列出某个项目的 issue
GET /repos/:owner/:repo/issues/:number           获取某个项目的某个 issue
POST /repos/:owner/:repo/issues                  为某个项目创建 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. 对于错误数据，默认使用 dingo 的错误格式， 如下结构：

'message' => ':message',          // 错误的具体描述
'errors' => ':errors',            // 参数的具体错误描述，422 等状态提供，（此项非必需）
'status_code' => ':status_code',  // http状态码
'debug' => ':debug',              // debug 信息，非生产环境提供

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

• 下面是通用的资源异常的列表，它们都会返回 HTTP 422 状态码。参考

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

**如果需要展示详细错误，请勿放到 'message' 里， 参考： **

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

• 常用异常参考：