ApiManual.md · XDU2023-SoftwareEngineering/scheme

# API手册

* **注意**：出于安全考虑，<span style="color:red">使用POST发送请求，尤其是登录、注册请求</span>
* 请求时，将JWT放入HTTP请求头中的**Authorization**段
* 响应数据`"api.status"`与HTTP状态码类似，具体释义以附表为准
* 处理服务器响应前，**先验证`api.status`状态码**，响应是否有效、哪些部分有效根据状态码判断
* 数据类型标识前`?`表示该字段可以为空
* API路由路径中的v\*.\*字段代表API版本号，与请求数据中"apiVersion"字段应相同，不同会报错

> 版本号格式：vx.x，例如：v1.0、v1.14、v5.14
>
> 一般而言，小版本不同不会造成api请求与响应格式变化，但大版本不保证

* 若API有版本变化，更新版本中仅列出有变化的API，未列出代表没有新版本
* 下文仅指定API路由路径，开发时自行替换

>  例：服务器127.0.0.1:8080，API为api/v1.0/login，则对应为127.0.0.1:8080/api/v1.0/login

## 用户身份相关

### 注册

* 请求：`api/v1.0/user/register`
```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "userParam": {
        "email": string,
        "password": string,
        "name": ?string
    }
}
```

* 响应：

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number
    },
    "result": {
        "description": string,
        "userConfig": {
            "email": string,
            "name": string,
            "userID": string
        },
        "token": JWT
    }
}
```

### 登录

* 请求：`api/v1.0/user/login`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "userParam": {
        "email": string,
        "password": string
    }
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "userConfig": {
            "email": string,
            "name": string,
            "userID": string
        },
        "token": JWT
    }
}
```

### 修改用户名

* 请求：`api/v1.0/user/changeName`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        },
        "newConfig": {
            "newName": string
        }
    }
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newConfig": {/* same as newConfig in request */}
    }
}
```

### 修改密码

* 请求：`api/v1.0/user/changePassword`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string,
            "oldPassword": string
        },
        "newConfig": {
            "newPassword": string
        }   
    }
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "user": {
        	"email": string,
            "userID": string,
            "userName": string
        }
    }
}
```

### 获取有效JWT对应用户信息

* 请求：`api/v1.0/user/getUserProfile`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "user": {
            "email": string,
            "userID": string,
            "name": string
        }
    }
}
```

### 主动更新JWT

* 请求：`api/v1.0/user/updateJWT`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT
    }
}
```

## 记账相关

### 新增账户

* 请求：`api/v1.0/feature/addAccount`

> "accountConfig"字段内"type"数值释义见附表

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        },
        "accountConfig": {
            "name": string,
            "priority": number,
            "type": number
        }
    }
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT
        "email": string,
        "accountID": string,
        "accountConfig": { /* same as request's accountConfig */ }
    }
}
```

### 修改已有账户

- 请求：`api/v1.0/feature/editAccount`

> `param.target.isDelete`字段用于标记本次修改是否为删除操作，若值为true则服务器不会读取位于`param.target.newAccountConfig`字段中的数据，且此字段应置为null

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        },
        "target": {
            "accountID": string,
            "isDelete": bool
            "newAccountConfig": {
                "name": string,
                "priority": number,
                "type": number
            }
        }
    }
}
```

- 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT,
        "target": { /* same as target in request */ }
    }
}
```

### 获取账户信息

* 请求：`api/v1.0/feature/getAccounts`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        },
        "filter": {
            "type": number
        }
    }
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT,
        "queryData": list(Object) // list of account
        /* {
            "accountID": string,
            "name": string,
            "priority": number,
            "type": number
        } */
    }
}
```

### 新增账目

* 请求`api/v1.0/feature/addBill`

> "billConfig"字段"type"数值释义见附表

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        },
        "billConfig":{
            "time": string,        // "YYYY-MM-DD HH-MM-SS"
            "cost": number,
            "tag": string,
            "expression": string,        // eg."12+2"
            "type": number,
            "account": string	   // accountID
        }
    }
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": number 
    },
    "result": {
        "description": string,
        "newToken": JWT,
        "email": string,
        "userID": string,
        "billID": string
    }
}
```

### 修改已有账目

- 请求：`api/v1.0/feature/editBill`

> `param.target.isDelete`字段用于标记本次修改是否为删除操作，若值为true则服务器不会读取位于`param.target.newBillConfig`字段中的数据，且此字段应置为null

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        },
        "target": {
            "billID": string,
            "isDelete": bool
            "newBillConfig": {
                "time": string,
                "cost": number,
                "tag": string,
                "expression": string,
                "type": number,
            	"account": string	// accountID
            }
        }
    }
}
```

- 响应

````json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT,
        "target": { /* same as target in request */ }
    }
}
````

### 获取账目信息

* 请求：`api/v1.0/feature/getBills`

> `param.filter.activate`字段标记要使用的筛选器，在activate字典中被标记为`true`的筛选器其中的条件才会被服务器读取。
>
> eg. `activate = {"time": true, "type": true}`，则服务器只读取`param.filter.time`和`param.filter.type`字段中的筛选条件，其他两个不会被读取且应当被置为**null**

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        },
        "filter": {
            "activate": {
                "time": ?bool,
                "type": ?bool,
                "account": ?bool,
                "cost": ?bool
            },
            "time": {
                "from": date, // YYYY-MM-DD
                "to": date
            },
            "type": number,
            "account": string, // accountID
            "cost": [min, max] // var: number
        }
    }
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT,
        "queryData": list(Object) // list of bill
        /* {
            "billID": string,
            "time": string,
            "cost": number,
            "tag": string,
            "type": number,
            "account": string,
            "accountName": string,
            "expression": string
        } */
    }
}
```

## 财报功能

### 月度数据

* 请求：`api/v1.0/financial/getMonthReport`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        },
        "filter": {
            "time": date    // YYYY-MM
        }
    }
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT,
        "filter": { /* same as filter in request */ },
        "limit": number,
        "summary": list(object)
        /* {
            "type": string,
            "sum": number,
            "percentage": number,    //without '%'
        } */
    }
}
```

## 随手记相关

### 获取内容

* 请求：`api/v1.0/notebook/getNote`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "noteID": string
    }
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT,
        "note": {
        	"noteID": string,
            "title": string,
            "rawContent": string
        }
    }
}
```

### 新增内容

* 请求：`api/v1.0/notebook/addNote`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        },
        "note": {
            "title": string,
            "rawContent": string
        }
    }
}
```

* 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT,
        "noteID": string,
        "noteTitle": string,
        "noteDate": date    // YYYY-MM-DD
    }
}
```

### 修改内容

- 请求：`api/v1.0/notebook/editNote`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        },
        "target": {
            "noteID": string,
            "isDelete": bool    // if true, "newNoteConfig" should be null
            "newNoteConfig": {
                "title": string,
                "content": string,
                "date": date
            }
        }
    }
}
```

- 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT
    }
}
```

### 获取所有随手记（目录）

- 请求：`api/v1.0/notebook/getNotes`

```json
{
    "timestamp": date,
    "apiVersion": "v1.0",
    "param": {
        "user": {
            "email": string,
            "userID": ?string
        }
    }
}
```

- 响应

```json
{
    "timestamp": date,
    "api": {
        "version": "v1.0",
        "status": Number 
    },
    "result": {
        "description": string,
        "newToken": JWT,
        "queryData": list(Object) // list of notes
        /* {
            "noteID": string,
            "date": number(js-timestamp),
            "title": string
        } */
    }
}
```

# 附表

## account type

| type id |        description        |
| :-----: | :-----------------------: |
|    1    |         cash 现金         |
|    2    |       card 银行卡等       |
|    3    | ePay 支付宝等(账户内零钱) |

## bill type

| type id |     description      |
| :-----: | :------------------: |
|    0    |     income 收入      |
|    1    |       food 食        |
|    2    |       drink 饮       |
|    3    | transportation 交通  |
|    4    |    shopping 消费     |
|    5    |  entertainment 娱乐  |
|    6    |      housing 住      |
|    7    | electronics 电子产品 |
|    8    |     medical 医药     |
|    9    |      misc 其他       |

## API status code

| status code |                      description                       |
| :---------: | :----------------------------------------------------: |
|     200     |               无特殊情况，可读取相应字段               |
|     201     |                 请求成功并创建新的资源                 |
|     202     |          已经接受请求，但加入调度队列等待执行          |
|     204     |             服务器成功处理，但响应数据为空             |
|     205     |   服务器处理成功，用户终端应重置文档视图，如清除表单   |
|     301     |     此为旧版本API，当前可用但随时可能废弃，请升级      |
|     302     |         此为旧版本API，当前可用且暂无废弃计划          |
|     400     |                    请求数据格式错误                    |
|     401     |                    用户身份核验失败                    |
|     403     |                   服务器拒绝回应请求                   |
|     404     |                    API路由地址错误                     |
|     405     |                     请换用POST请求                     |
|     406     |               （查询类API）筛选条件冲突                |
|     407     |         身份核验失败，JWT已过期，需要重新登陆          |
|     408     | 请求数据中时间戳与服务器执行时时间戳时间跨度过大，超时 |
|     410     |                  请求版本API已被废弃                   |
|     411     |       未在HTTP请求头Authorization段中找到有效JWT       |
|     500     |              服务器内部错误，请联系管理员              |
|     501     |                API仍在实现中，现未开放                 |
|     600     |     仅在`主动更新JWT`API中出现，标记`newToken`有效     |
|     601     |        响应成功且JWT即将过期，newToken字段有效         |

XDU2023-SoftwareEngineering/scheme

简介

发行版 (8)

贡献者

近期动态

XDU2023-SoftwareEngineering/scheme .gitee-modal { width: 500px !important; }

简介

发行版 (8)

贡献者

近期动态

搜索帮助

XDU2023-SoftwareEngineering/scheme