# API 合约

> 本文定义后端 API 的目标形状。实现前可细化，但不要在代码里另起一套不兼容接口。

如果项目没有后端 API，可改成本地模块接口、CLI 参数或事件合约。

## 通用约定

- 传输：【JSON over HTTPS / GraphQL / gRPC / 本地函数调用】。
- 鉴权：【Session Cookie / Bearer Token / 无】。
- 请求体和响应体编码：【UTF-8 JSON】。
- 时间格式：【ISO 8601 / Unix timestamp】。
- 未登录访问需要权限的接口时返回：【401 / 403】。

通用错误响应：

```json
{
  "error": {
    "code": "bad_request",
    "message": "请求参数不正确"
  }
}
```

## 账号

### `POST /api/auth/login`

请求：

```json
{
  "email": "user@example.com",
  "password": "password"
}
```

成功响应：

```json
{
  "user": {
    "id": 1,
    "email": "user@example.com"
  }
}
```

## 核心资源

把项目的核心资源按 REST 或其他风格写清楚。

### `GET /api/items`

成功响应：

```json
{
  "items": [
    {
      "id": 1,
      "name": "示例"
    }
  ]
}
```

### `POST /api/items`

请求：

```json
{
  "name": "示例"
}
```

成功响应返回新增资源。

## 待实现时确认

- 参数校验规则。
- 分页、排序、筛选方式。
- 重复提交是否幂等。
- 错误码枚举。
- 鉴权过期时间和刷新策略。