说明
# 说明文档
本文档编写目的是说明api文档的使用方法以及对于文档中一些可能引起歧义的部分的补充说明，因此不会讲解语言语法等无关内容。如果语法看不懂或某个函数不会用，请自行百度（需要我帮你百度吗.jpg）。
## 部分名词解释
### 用户
目前(2020-07-22)，本项目的用户分为两类，一类为学生，另一类为教师。他们都可以使用本项目开发的软件进行实验室预约和使用。因为这两类用户的编号格式不同，在2020年4月左右设计成了两类不同的用户，并将数据存储于不同的表中。除了学号和工号以外，这两类用户没有本质区别。（但是有可能以后会给教师用户增加一些功能。）
### 管理员
管理员(有的文档中称作负责人，当时用有道搜出来是`principal`)指的是实验室的管理人员，每个管理员的权限仅限于审核用户的实验室使用申请，以及发布和删除通知。日后可能还会有更多权限，但不会有`administrator`意义上的管理员。
### 通知
四月在设计数据库时，将通知设计为了两类，临时类通知和长久通知，临时类通知有`expire字段`，会在到时间后删除，但是目前还没有想好如何删除过期的临时通知，其他方面二者依然没有本质区别。
此外，`通知`最初设想时对应的是实验室门口贴着的纸质通知，所以是由管理员发出的，仅限于管理员所负责的实验室的通知。设计时没有考虑大范围的全校通知。
## API介绍
### API是什么
你可以认为一个API就是一个在服务器上的函数（类似于小程序的云函数），就像调用你代码中写的函数一样，我们的API同样需要参数，同样有返回结果。调用一个API实质上是向服务器发送了一个HTTP请求，运行在服务器上的[程序（服务端）](https://github.com/Woodykaixa/BJUTLabServer)接收到请求后，会根据你请求的具体地址调用对应的函数。然后把函数运行的结果使用JSON格式发送回来。
### 错误提示
调用API就是调用一个函数，同样可能会存在参数缺失或参数不符合要求的情况，不同于调用代码中已存在的函数，调用API是没有参数提示的。如果的参数不全或有错，API将不会执行逻辑部分，而是返回如下格式的JSON用于提示。
```json
{
"err": "错误提示"
}
```
全部错误提示如下。假定你调用的API中有一个参数`paramA`
+ `Invalid parameter: paramA has wrong format` 参数格式错误
+ `Invalid parameter: paramA has wrong format(format)` 括号中的format是一个具体格式，比如对于学号，format会替换为`^\d{8}$`。(要求学号是八位数字)
+ `Invalid parameter: unsupported type: paramA` 当`paramA`是类型代码时，会返回此信息
+ `Invalid parameter: paramA is out of range([a,b] seconds)` 当`paramA`是日期类型时，返回此信息表示日期超时(对于需要提交日期的API，通常的限制是服务器收到请求时候的日期时间和paramA作差，时间差在五分钟以上则返回此信息)
+ `Invalid parameter: paramA is out of range` 当paramA是数字并且不符合大小限制时返回此信息。
除此之外，[HTTP状态码](https://baike.baidu.com/item/HTTP%E7%8A%B6%E6%80%81%E7%A0%81/5053660?fr=aladdin#4)也会反映一定的信息。
### API使用方式
使用`HTTP请求方法`向`请求地址`发送`请求参数`，如果调用成功，会通过`响应参数`来返回API调用结果。
#### 演示
以下示例使用了浏览器环境的[Fetch API](https://developer.mozilla.org/zh-CN/docs/Web/API/Fetch_API/Using_Fetch)。发送Web请求的方式有很多种，**文档举例使用fetch不代表只能这么写**。你也可以使用[JQuery](https://api.jquery.com/)、[XMLHttpRequest](https://developer.mozilla.org/zh-CN/docs/Web/API/XMLHttpRequest)或其他方法。小程序请参照[微信开发者文档->网络->发起请求](https://developers.weixin.qq.com/miniprogram/dev/api/network/request/wx.request.html)章节。
```javascript
const url='https://api.bjutlab.cn/example/exampleAPI' // 开发者服务器接口地址，example表示这是一个例子，不要尝试直接复制粘贴。
// GET方法使用url传递参数，在url后面使用'?'分隔，然后用'参数名=参数值'的方式传递参数(键值对)，每个键值对之间使用'&'分隔
fetch(url+'?param1=example¶m2=1').then(res => {
// https://api.bjutlab.cn/example/exampleAPI?param1=example¶m2=1
// ^
})
// POST方法传递参数，使用JSON格式或其他格式。
fetch(url, {
method: 'POST',
body: JSON.stringify({
param1: 'example', // 图中字体为红色的是必填参数
// param2: 1 字体为灰色的是可选参数，可以不填
})
}).then(res => {
// ...
});
```
---
## <>的含义
和Flask的URL变量一样。会Flask的就不用看了。
在api中用一对尖括号<>括起来的表示变量，在调用api时需要替换掉。示例：
```js
// https://api.bjutlab.cn/Example/exampleAPI/<user_id>
let exampleAPIurl = `https://api.bjutlab.cn/Example/exampleAPI/123456`;
fetch(exampleAPIurl);
```
有的时候，尖括号内的变量还会注明类型，例如：`https://api.bjutlab.cn/Example/exampleAPI/<int:user_id>`
此时要求`user_id`为数字，否则会返回HTTP状态码`404 Not Found`
```js
// https://api.bjutlab.cn/Example/exampleAPI/<int:user_id>
let right = '123456'; // 正确示范，即使要求是int类型也不必必须是`number`类型，一个全是数字的字符串也是可以的
let wrong = 'NotANumber'; // 错误示范
let prefix = `https://api.bjutlab.cn/Example/exampleAPI/`;
fetch(prefix + right).then(res => {
console.log(res.ok); // res.ok为true
});
fetch(prefix + right).then(res => {
console.log(res.ok); // res.ok为false
});
```