Skip to content

Commit bc8522e

Browse files
RabithuaRabithua
committed
Add API user guide documentation
Added user guide markdown files for Changes API, Login API, and User API under doc/userguide/. These documents provide usage instructions, request/response examples, and client recommendations for each API.
1 parent 565efff commit bc8522e

3 files changed

Lines changed: 731 additions & 0 deletions

File tree

‎doc/userguide/CHANGES-API.md‎

Lines changed: 304 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,304 @@
1+
## Changes（变更记录）接口使用指南
2+
3+
本指南面向对接方，说明如何使用变更记录相关的接口进行笔记变更历史的查询和同步。仅包含使用方法与示例，不涉及实现细节。
4+
5+
### 基础信息
6+
- **基础路径**: `/v2/api/changes`
7+
- **统一响应**: `{ code: number, message: string, data: any }`（`code=0` 表示成功）
8+
- **认证方式**: 所有接口都需要认证，加请求头 `Authorization: Bearer <accessToken>`
9+
10+
### 变更记录说明
11+
变更记录用于追踪笔记的创建、更新、删除操作，主要用于客户端同步场景。
12+
13+
**变更记录字段**：
14+
- `id`: 变更记录ID（UUID）
15+
- `originid`: 原始笔记ID（用于客户端同步，即使笔记被删除也保留）
16+
- `roteid`: 笔记ID（可能为 `null`，如果笔记被删除）
17+
- `action`: 操作类型，可选值：`"CREATE"`（创建）、`"UPDATE"`（更新）、`"DELETE"`（删除）
18+
- `userid`: 用户ID
19+
- `createdAt`: 变更时间
20+
- `rote`: 关联的笔记信息（如果笔记存在，包含笔记的详细信息）
21+
22+
---
23+
24+
### 1) 根据原始笔记ID获取变更记录
25+
- **方法**: GET
26+
- **URL**: `/v2/api/changes/origin/:originid`
27+
- **Headers**: `Authorization: Bearer <accessToken>`（必填）
28+
- **路径参数**:
29+
- `originid`: string（原始笔记ID，UUID格式）
30+
- **Query 参数**:
31+
- `skip`: number（可选，分页偏移量）
32+
- `limit`: number（可选，每页数量）
33+
34+
请求示例（cURL）:
35+
36+
```bash
37+
curl -X GET 'https://your-domain.com/v2/api/changes/origin/<ORIGIN_ID>?skip=0&limit=20' \
38+
-H 'Authorization: Bearer <ACCESS_TOKEN>'
39+
```
40+
41+
成功响应示例（200）：
42+
43+
```json
44+
{
45+
"code": 0,
46+
"message": "success",
47+
"data": [
48+
{
49+
"id": "change-uuid",
50+
"originid": "origin-uuid",
51+
"roteid": "rote-uuid",
52+
"action": "UPDATE",
53+
"userid": "user-uuid",
54+
"createdAt": "2024-01-01T12:00:00.000Z",
55+
"rote": {
56+
"id": "rote-uuid",
57+
"title": "笔记标题",
58+
"content": "笔记内容",
59+
"type": "Rote",
60+
"tags": ["标签1"],
61+
"state": "public",
62+
"archived": false,
63+
"pin": false,
64+
"editor": "normal",
65+
"createdAt": "2024-01-01T00:00:00.000Z",
66+
"updatedAt": "2024-01-01T12:00:00.000Z"
67+
}
68+
}
69+
]
70+
}
71+
```
72+
73+
说明：
74+
- 返回结果按创建时间降序排列（最新的在前）
75+
- 只返回当前登录用户的变更记录
76+
- 如果笔记被删除，`rote` 字段可能为 `null`，但 `originid` 仍然保留
77+
78+
可能的错误：
79+
- 401 未认证（需要登录）
80+
- 400 原始笔记ID格式错误或缺失
81+
82+
---
83+
84+
### 2) 根据笔记ID获取变更记录
85+
- **方法**: GET
86+
- **URL**: `/v2/api/changes/rote/:roteid`
87+
- **Headers**: `Authorization: Bearer <accessToken>`（必填）
88+
- **路径参数**:
89+
- `roteid`: string（笔记ID，UUID格式）
90+
- **Query 参数**:
91+
- `skip`: number（可选，分页偏移量）
92+
- `limit`: number（可选，每页数量）
93+
94+
请求示例（cURL）:
95+
96+
```bash
97+
curl -X GET 'https://your-domain.com/v2/api/changes/rote/<ROTE_ID>?skip=0&limit=20' \
98+
-H 'Authorization: Bearer <ACCESS_TOKEN>'
99+
```
100+
101+
成功响应示例（200）：
102+
103+
```json
104+
{
105+
"code": 0,
106+
"message": "success",
107+
"data": [
108+
{
109+
"id": "change-uuid",
110+
"originid": "origin-uuid",
111+
"roteid": "rote-uuid",
112+
"action": "CREATE",
113+
"userid": "user-uuid",
114+
"createdAt": "2024-01-01T00:00:00.000Z",
115+
"rote": {
116+
"id": "rote-uuid",
117+
"title": "笔记标题",
118+
"content": "笔记内容",
119+
"type": "Rote",
120+
"tags": ["标签1"],
121+
"state": "public",
122+
"archived": false,
123+
"pin": false,
124+
"editor": "normal",
125+
"createdAt": "2024-01-01T00:00:00.000Z",
126+
"updatedAt": "2024-01-01T00:00:00.000Z"
127+
}
128+
}
129+
]
130+
}
131+
```
132+
133+
说明：
134+
- 返回结果按创建时间降序排列（最新的在前）
135+
- 只返回当前登录用户的变更记录
136+
- 如果笔记被删除，`roteid` 可能为 `null`，此时不会返回该变更记录
137+
138+
可能的错误：
139+
- 401 未认证（需要登录）
140+
- 400 笔记ID格式错误或缺失
141+
142+
---
143+
144+
### 3) 根据用户ID获取变更记录
145+
- **方法**: GET
146+
- **URL**: `/v2/api/changes/user`
147+
- **Headers**: `Authorization: Bearer <accessToken>`（必填）
148+
- **Query 参数**:
149+
- `skip`: number（可选，分页偏移量）
150+
- `limit`: number（可选，每页数量）
151+
- `action`: string（可选，过滤操作类型：`"CREATE"`、`"UPDATE"`、`"DELETE"`）
152+
153+
请求示例（cURL）:
154+
155+
```bash
156+
curl -X GET 'https://your-domain.com/v2/api/changes/user?skip=0&limit=20&action=UPDATE' \
157+
-H 'Authorization: Bearer <ACCESS_TOKEN>'
158+
```
159+
160+
成功响应示例（200）：
161+
162+
```json
163+
{
164+
"code": 0,
165+
"message": "success",
166+
"data": [
167+
{
168+
"id": "change-uuid",
169+
"originid": "origin-uuid",
170+
"roteid": "rote-uuid",
171+
"action": "UPDATE",
172+
"userid": "user-uuid",
173+
"createdAt": "2024-01-01T12:00:00.000Z",
174+
"rote": {
175+
"id": "rote-uuid",
176+
"title": "笔记标题",
177+
"content": "笔记内容",
178+
"type": "Rote",
179+
"tags": ["标签1"],
180+
"state": "public",
181+
"archived": false,
182+
"pin": false,
183+
"editor": "normal",
184+
"createdAt": "2024-01-01T00:00:00.000Z",
185+
"updatedAt": "2024-01-01T12:00:00.000Z"
186+
}
187+
}
188+
]
189+
}
190+
```
191+
192+
说明：
193+
- 返回当前登录用户的所有变更记录
194+
- 返回结果按创建时间降序排列（最新的在前）
195+
- 可以通过 `action` 参数过滤特定类型的操作
196+
197+
可能的错误：
198+
- 401 未认证（需要登录）
199+
200+
---
201+
202+
### 4) 获取指定时间戳之后的变更记录
203+
- **方法**: GET
204+
- **URL**: `/v2/api/changes/after`
205+
- **Headers**: `Authorization: Bearer <accessToken>`（必填）
206+
- **Query 参数**:
207+
- `timestamp`: string（必填，时间戳，支持多种格式）
208+
- `skip`: number（可选，分页偏移量）
209+
- `limit`: number（可选，每页数量）
210+
- `action`: string（可选，过滤操作类型：`"CREATE"`、`"UPDATE"`、`"DELETE"`）
211+
212+
**时间戳格式支持**：
213+
- ISO 8601 格式：`"2024-01-01T00:00:00.000Z"` 或 `"2024-01-01T00:00:00Z"`
214+
- Unix 时间戳（秒）：`"1704067200"`
215+
- Unix 时间戳（毫秒）：`"1704067200000"`
216+
217+
请求示例（cURL）:
218+
219+
```bash
220+
# 使用 ISO 8601 格式
221+
curl -X GET 'https://your-domain.com/v2/api/changes/after?timestamp=2024-01-01T00:00:00.000Z&skip=0&limit=20' \
222+
-H 'Authorization: Bearer <ACCESS_TOKEN>'
223+
224+
# 使用 Unix 时间戳（秒）
225+
curl -X GET 'https://your-domain.com/v2/api/changes/after?timestamp=1704067200&skip=0&limit=20' \
226+
-H 'Authorization: Bearer <ACCESS_TOKEN>'
227+
```
228+
229+
成功响应示例（200）：
230+
231+
```json
232+
{
233+
"code": 0,
234+
"message": "success",
235+
"data": [
236+
{
237+
"id": "change-uuid-1",
238+
"originid": "origin-uuid-1",
239+
"roteid": "rote-uuid-1",
240+
"action": "CREATE",
241+
"userid": "user-uuid",
242+
"createdAt": "2024-01-01T01:00:00.000Z",
243+
"rote": {
244+
"id": "rote-uuid-1",
245+
"title": "笔记标题1",
246+
"content": "笔记内容1",
247+
"type": "Rote",
248+
"tags": ["标签1"],
249+
"state": "public",
250+
"archived": false,
251+
"pin": false,
252+
"editor": "normal",
253+
"createdAt": "2024-01-01T01:00:00.000Z",
254+
"updatedAt": "2024-01-01T01:00:00.000Z"
255+
}
256+
},
257+
{
258+
"id": "change-uuid-2",
259+
"originid": "origin-uuid-2",
260+
"roteid": "rote-uuid-2",
261+
"action": "UPDATE",
262+
"userid": "user-uuid",
263+
"createdAt": "2024-01-01T02:00:00.000Z",
264+
"rote": {
265+
"id": "rote-uuid-2",
266+
"title": "笔记标题2",
267+
"content": "笔记内容2",
268+
"type": "Rote",
269+
"tags": ["标签2"],
270+
"state": "private",
271+
"archived": false,
272+
"pin": false,
273+
"editor": "normal",
274+
"createdAt": "2024-01-01T00:00:00.000Z",
275+
"updatedAt": "2024-01-01T02:00:00.000Z"
276+
}
277+
}
278+
]
279+
}
280+
```
281+
282+
说明：
283+
- 返回指定时间戳之后的所有变更记录（不包含该时间戳）
284+
- 返回结果按创建时间升序排列（最早的在前），方便客户端按顺序处理
285+
- 只返回当前登录用户的变更记录
286+
- 可以通过 `action` 参数过滤特定类型的操作
287+
- 如果使用 ISO 8601 格式且包含特殊字符，需要进行 URL 编码
288+
289+
可能的错误：
290+
- 401 未认证（需要登录）
291+
- 400 时间戳参数缺失或格式错误
292+
293+
---
294+
295+
### 客户端使用建议
296+
- **同步场景**: 使用 `/changes/after` 接口配合时间戳，可以实现增量同步。客户端记录最后一次同步的时间戳，定期调用该接口获取新的变更记录
297+
- **时间戳格式**: 推荐使用 ISO 8601 格式（`YYYY-MM-DDTHH:mm:ss.sssZ`），如果使用 Unix 时间戳，注意区分秒和毫秒
298+
- **分页处理**: 所有查询接口都支持 `skip` 和 `limit` 参数，建议合理设置每页数量，避免一次性加载过多数据
299+
- **操作类型过滤**: 可以通过 `action` 参数过滤特定类型的操作，例如只获取创建或更新操作
300+
- **originid vs roteid**:
301+
- `originid` 是原始笔记ID，即使笔记被删除也保留，用于客户端同步场景
302+
- `roteid` 是当前笔记ID，如果笔记被删除，该字段可能为 `null`
303+
- **笔记信息**: 变更记录中包含关联的笔记信息（`rote` 字段），如果笔记被删除，该字段可能为 `null`
304+

0 commit comments

Comments
 (0)