>[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。