资源实体
在feat.com上面定义的资源都含有一下基本字段
interface ResourceBasic {
created_at: string;
updated_at: string;
kind: string;
}API 请求
地址规范
发起API请求地址，地址必须以“/”字符作为结尾
分页请求
对于支持分页的API，一般的分页，可以采用 page={page}&page_size={pageSize} 的方式进行调用
排序
当列表API支持按字段排序时，可以采用一下两种形式进行调用，一种是按字段升序，一种是按字段降序
ordering={fieldName}按字段升序排列 (ascend)ordering=-{fieldName}按字段降序排列 (descend)
查询
当API接口支持关键词查询时，统一使用 search={keyword} 的方式调用
API 响应
成功的返回
资源响应
interface ResourceResponse {
data: Any
}分页响应
interface PaginationResponse {
data: Array<T>
pagination: Pagination
}分页数据结构
interface Pagination{
current_page: integer;
page_size: integer;
total_count: integer;
total_pages: integer;
next: integer | null;
previous: integer | null;
}操作状态返回
对于不便于使用资源作为返回结果的接口，我们定义了定义指数据返回叫StatusResponse。StatusResponse 里面定义了一个 success 字段来表示处理结构，以及一个可选的data 字段来描述相关信息
interface StatusResponse {
success: Boolean;
data: Object | null;
}错误或异常返回
Feat Open API 为错误｜异常的返回定义了一个基础范式，方面开发者处理接口异常的问题。
interface ErrorResponse {
code: string; // 错误代码，一般为 大写字母
message?: string; // 可读的消息描述
data: Object | null; // 额外的数据
}常见的错误类型
- Not Authentication
- Authorization Failed
- Validation Exception
- Resource Not Found
- Server Error
Not Authentication
HTTP Status 401
请求来源缺少授权凭证或身份认证信息
{
code: 'not_authenticated',
message: String
}Authentication Failed
HTTP Status 401
请求来源提供了错误的授权凭证或身份认证信息
{
code: 'authentication_failed',
message: String
}Validation Exception
HTTP Status 400
提交表单验证失败。提交上接口的数据不符合表单对应字段的要求。
{
code: 'VALIDATION_EXCEPTION',
data: {
[field]: Array<string>,
}
}Resource Not Found
HTTP Status 404
访问的对象不存在。通过该接口访问的数据对象不存在或已删除。
{
code: 'NOT_FOUND',
message: String
}Server Error
HTTP Status 500
内部服务错误。
{
code: 'INTERNAL_ERROR',
message: String
}