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."
        ]
    }
}

• 常用异常参考：

异常	描述	状态码
AccessDeniedHttpException	拒绝访问异常	403
BadRequestHttpException	错误请求异常	400
ConflictHttpException	冲突异常	409
GoneHttpException	资源已经不存在异常	410
HttpException	HTTP异常	500
LengthRequiredHttpException	需要内容长度信息异常	411
MethodNotAllowedHttpException	方法不允许异常	405
NotAcceptableHttpException	不可接受异常	406
NotFoundHttpException	找不到资源异常	404
PreconditionFailedHttpException	请求头先决条件未满足异常	412
PreconditionRequiredHttpException	缺少先决条件头信息异常	428
ServiceUnavailableHttpException	服务不可用异常	503
TooManyRequestsHttpException	请求频繁异常	429
UnauthorizedHttpException	未授权异常	401
UnsupportedMediaTypeHttpException	不支持的媒体类型异常	415