# 后端API参考

## REST API v2 (推荐)

基础路径: `/api/v2/`

### 文档操作
```
GET    /api/v2/document/{pagetype}              # 列表查询
       参数: fields, filters, order_by, limit, limit_start
GET    /api/v2/document/{pagetype}/{name}/      # 获取单个
POST   /api/v2/document/{pagetype}              # 创建 (Body: JSON)
PUT    /api/v2/document/{pagetype}/{name}/      # 更新
DELETE /api/v2/document/{pagetype}/{name}/      # 删除
GET    /api/v2/document/{pagetype}/{name}/copy  # 复制
POST   /api/v2/document/{pagetype}/{name}/action/{method}/  # 执行方法
```

### 元数据
```
GET /api/v2/pagetype/{pagetype}/meta   # 获取PageType元数据
GET /api/v2/pagetype/{pagetype}/count  # 获取记录数
```

## 旧版Data API

基础路径: `/api/data/`
```
GET    /api/data/{pagetype}           # 列表
GET    /api/data/{pagetype}/{name}    # 获取
POST   /api/data/{pagetype}           # 创建
PUT    /api/data/{pagetype}/{name}    # 更新
DELETE /api/data/{pagetype}/{name}    # 删除
```

## RPC调用

```
POST /api/action/{dotted.method.path}
Body: { arg1: value1, ... }
```

### 常用RPC方法

**客户端操作** (jingrow.client):
- `jingrow.client.get_list` - 获取列表
- `jingrow.client.get` - 获取单个
- `jingrow.client.insert` - 插入
- `jingrow.client.save` - 保存
- `jingrow.client.delete` - 删除
- `jingrow.client.get_count` - 获取记录数

**表单加载** (jingrow.desk.form.load):
- `jingrow.desk.form.load.getpage` - 获取文档(含__onload)
- `jingrow.desk.form.load.getpagetype` - 获取PageType定义

**搜索**:
- `jingrow.desk.search.search_widget` - 通用搜索

**认证**:
- `/api/action/login` - 登录
- `/api/action/logout` - 登出

## Python API

### 文档操作
```python
import jingrow

# 获取文档
pg = jingrow.get_pg("PageType", "name")

# 创建文档
pg = jingrow.new_pg("PageType", field1="value1")
pg.insert()

# 更新文档
pg.field = "value"
pg.save()

# 删除文档
jingrow.delete_pg("PageType", "name")

# 重命名
jingrow.rename_pg("PageType", "old_name", "new_name")
```

### 数据库查询
```python
# 获取单个字段值
value = jingrow.db.get_value("PageType", "name", "field")

# 获取多个字段
val1, val2 = jingrow.db.get_value("PageType", "name", ["field1", "field2"])

# 获取列表(忽略权限)
records = jingrow.get_all("PageType", 
    filters={"field": "value"},
    fields=["name", "field1"],
    order_by="creation desc",
    limit=10
)

# 获取列表(检查权限)
records = jingrow.get_list("PageType", filters={"status": "Open"})

# SQL查询
result = jingrow.db.sql("SELECT * FROM `tabPageType` WHERE ...", as_dict=True)

# 存在性检查
exists = jingrow.db.exists("PageType", "name")
exists = jingrow.db.exists("PageType", {"field": "value"})

# 获取记录数
count = jingrow.db.count("PageType", {"status": "Open"})
```

### 白名单方法

使用 `@jingrow.whitelist()` 装饰器暴露API:
```python
@jingrow.whitelist()
def my_api_method(arg1, arg2):
    return {"result": "data"}

# 允许访客访问
@jingrow.whitelist(allow_guest=True)
def public_method():
    pass

# 限制HTTP方法
@jingrow.whitelist(methods=["POST"])
def post_only_method():
    pass
```
调用: `POST /api/action/module.path.my_api_method`

### 权限检查
```python
# 检查权限
jingrow.has_permission("PageType", "read", pg=pg)
jingrow.has_permission("PageType", "write")

# 仅允许特定角色
jingrow.only_for(["System Manager", "Administrator"])

# 文档级别权限检查
pg.check_permission("read")  # 抛异常如果无权限
```

### 工具函数
```python
# 获取PageType元数据
meta = jingrow.get_meta("PageType")

# 消息提示
jingrow.msgprint("操作成功")

# 抛出错误
jingrow.throw("错误消息")
jingrow.throw("权限不足", jingrow.PermissionError)

# JSON序列化
json_str = jingrow.as_json(data)

# 缓存
jingrow.cache.set_value("key", value)
value = jingrow.cache.get_value("key")

# 后台任务
jingrow.enqueue("module.method", arg1=value)
```

### Page类生命周期钩子
```python
class MyPageType(Page):
    def validate(self):         # 保存前验证
        pass
    def before_save(self):      # 保存前处理
        pass
    def after_insert(self):     # 插入后
        pass
    def on_update(self):        # 更新后
        pass
    def on_submit(self):        # 提交后
        pass
    def on_cancel(self):        # 取消后
        pass
    def on_trash(self):         # 删除后
        pass
```
