即时通信软件后端API文档
1 概述
magic_chat目标是一款类似微信的即时通信软件，其后端是Python代码 Django框架实现的，功能包括注册、登录、消息发送、消息查看、实时发送消息等。
相关代码已上传github:https://github.com/djldjl/magic_chat
本文是后端服务的API接口说明文档，为前端开发人员提供接口说明。以下分模块说明各个后端功能API。
2 用户管理相关API
2.1 注册
协议: http
方法: POST
路径: register/
|
参数 |
参数说明 |
参数样例 |
|
phone |
以电话为用户注册唯一标识 |
13910911111 |
|
password |
用户密码 |
123456 |
地址样例：http://127.0.0.1:8000/register/
备注：需要在headers中加入csrftoken
成功返回样例（json）：
{
"status": 200,
"msg": "用户注册成功"
}
2.2 登录
协议: http
方法: POST
路径: login/
|
参数 |
参数说明 |
参数样例 |
|
phone |
以电话为用户注册唯一标识 |
13910911111 |
|
password |
用户密码 |
123456 |
地址样例：http://127.0.0.1:8000/login/
备注：无
成功返回样例（json）：
{
"status": 200,
"msg": "用户登录成功",
"user_id": "e9eeb26cc8d64f53ad15e2d3c2cfe22f",
"token": "c976fb18ace2bf6b88976d3b2e46378f0412ae9a"
}
2.3 修改密码
协议: http
方法: POST
路径: password/
|
参数 |
参数说明 |
参数样例 |
|
new_password1 |
第一次输入新密码；不能为空 |
12345678 |
|
new_password2 |
第二次输入新密码 |
12345678 |
地址样例：http://127.0.0.1:8000/password/
备注：需要在headers中加入成功登录获取的token（Authorization：Token 140a1bf3e4909c8a6a8dc070ff13c807aec23bb4）
成功返回样例（json）：
{
"status": 200,
"msg": "修改密码成功"
}
2.4 登出
协议: http
方法: POST
路径: logout/
|
参数 |
参数说明 |
参数样例 |
|
无 |
|
|
地址样例：http://127.0.0.1:8000/logout/
备注：需要在headers中加入成功登录获取的token
成功返回样例（json）：
{
"status": 200,
"msg": "退出成功"
}
2.5 个人设置
2.5.1 查看用户个人设置
协议: http
方法: GET
路径: profile/
|
参数 |
参数说明 |
参数样例 |
|
无 |
|
|
地址样例：http://127.0.0.1:8000/profile/
备注：需要在headers中加入成功登录获取的token
成功返回样例（json）：
{
"data": {
"user_id": "e9eeb26cc8d64f53ad15e2d3c2cfe22f",
"email": null,
"phone": "13910911111",
"nickname": null,
"avatar_url": null,
"status_text": null
},
"status": 200,
"msg": "获取用户设置信息成功"
}
返回数据说明：
"user_id": 用户user_id，系统唯一,
"email": 用户email，可空,
"phone":用户电话，系统唯一,
"nickname": 用户昵称,
"avatar_url": 用户头像链接,
"status_text": 用户签名
2.5.2 设置用户个人设置
协议: http
方法: PUT
路径: profile/
|
参数 |
参数说明 |
参数样例 |
|
nickname |
昵称；可选 |
猫咪 |
|
avatar_url |
头像链接；可选 |
test.com/pic.jpg |
|
status_text |
个人签名；可选 |
太阳总会升起！ |
地址样例：http://127.0.0.1:8000/profile/
备注：需要在headers中加入成功登录获取的token
成功返回样例（json）：
{
"status": 200,
"msg": "修改用户设置成功",
"修改后data": {
"user_id": "e9eeb26cc8d64f53ad15e2d3c2cfe22f",
"email": null,
"phone": "13910911111",
"nickname": "猫咪",
"avatar_url": "test.com/pic.jpg",
"status_text": "太阳总会升起！"
}
}
3 通讯录相关API
3.1 获取联系人信息
协议: http
方法: GET
路径: contact/
|
参数 |
参数说明 |
参数样例 |
|
无 |
|
|
地址样例：http://127.0.0.1:8000/contact/
备注：需要在headers中加入成功登录获取的token
成功返回样例（json）：
{
"data": [
{
"contact_user_id": "75fe180ff2104f1da1dc6619aaccfa20",
"contact_phone": "13588888888",
"contact_nickname": "天空依然",
"contact_avatar_url": "http://test.com/pic",
"status": 1
}
],
"status": 200,
"msg": "获取通讯录成功"
}
返回数据说明：
"contact_user_id":联系人user_id,
"contact_phone":联系人电话,
"contact_nickname": 联系人电话,
"contact_avatar_url": 联系人头像链接,
"status": 联系人状态，1为正常，0为拉黑
3.2 添加联系人
协议: http
方法: POST
路径: contact/
|
参数 |
参数说明 |
参数样例 |
|
phone |
以电话为标识添加联系人 |
13588888888 |
地址样例：http://127.0.0.1:8000/contact/
备注：需要在headers中加入成功登录获取的token
成功返回样例（json）：
{
"status": 200,
"msg": "添加联系人成功"
}
3.3 删除联系人
协议: http
方法: DELETE
路径: contact/
|
参数 |
参数说明 |
参数样例 |
|
phone |
以电话为标识删除联系人 |
13588888888 |
地址样例：http://127.0.0.1:8000/contact/
备注：需要在headers中加入成功登录获取的token
成功返回样例（json）：
{
"status": 200,
"msg": "删除联系人成功"
}
4 消息获取和发送相关API
4.1 获取消息列表
协议: http
方法: GET
路径: message/list/
|
参数 |
参数说明 |
参数样例 |
|
无 |
|
|
地址样例：http://127.0.0.1:8000/message/list/
备注：需要在headers中加入成功登录获取的token
成功返回样例（json）：
{
"status": 200,
"msg": "获取会话列表成功",
"data": [
{
"id": 1,
"last_msg": "this is 111",
"last_msg_time": "2020-04-30 02:01:37.042768",
"msg_count": 2,
"msg_type": 0,
"status": 1,
"user_info": {
"user_id": "548f00a3034e41c9adb657568a1dd150",
"email": null,
"phone": "111",
"nickname": "猴子",
"avatar_url": "test.com/abc",
"status_text": null
},
"to_user_info": {
"user_id": "e708808d07d54fa4b594d0c4daf98c39",
"email": null,
"phone": "222",
"nickname": "小鸟",
"avatar_url": "http://test.com/abc",
"status_text": null
},
"self_msg_count": 0,
"to_user_msg_count": 0,
"cache_msg_count": "0"
},
]
}
返回数据说明：
"id": 会话ID，2用户文字通信即为1个会话,
"last_msg": 本会话最后一条消息内容,
"last_msg_time": 最后一条消息发送的时间,
"msg_count": 保留字段,
"msg_type": 消息类型，0为文本,
"status": 会话状态，1为正常,
"user_info":本用户id、电话、头像等信息,
"to_user_info":对方用户id、电话、头像等信息,
"self_msg_count": 本用户未读消息数,
"to_user_msg_count": 对方用户未读消息数,
"cache_msg_count":本用户未读消息数,
4.2 查看最新消息
协议: http
方法: GET
路径: message/
|
参数 |
参数说明 |
参数样例 |
|
user_chat_id |
所属会话ID；获取某个会话的消息 |
1 |
|
offset |
从哪一条消息开始展现；可选；默认0 |
5 |
|
limit |
每页展示几条消息；可选；默认5 |
3 |
地址样例：http://127.0.0.1:8000/message/
备注：需要在headers中加入成功登录获取的token
成功返回样例（json）：
{
"status": 200,
"msg": "获取该会话的消息成功",
"all_page_num": 9,
"data": [
{
"id": 27,
"send_time": "2020-04-29 12:01:10.404168",
"message": "今天29号",
"type": 0,
"status": 1,
"chat": 1,
"from_user": 6,
"to_user": 5
},
{
"id": 26,
"send_time": "2020-04-28 07:23:03.358066",
"message": "知道，我今天买了一件新衣服~",
"type": 0,
"status": 1,
"chat": 1,
"from_user": 6,
"to_user": 5
},
{
"id": 25,
"send_time": "2020-04-28 07:08:43.850539",
"message": "今天我第二次跟你说话",
"type": 0,
"status": 1,
"chat": 1,
"from_user": 5,
"to_user": 6
}
]
}
返回数据说明：
"all_page_num": 总共多少页,
"data": [
{
"id": 消息ID,
"send_time": 消息发送时间,
"message": 消息内容,
"type": 消息类型，0为文本,
"status": 消息状态，1为正常，2为撤回,
"chat": 所属会话ID,
"from_user": 发送用户ID,
"to_user": 目标用户ID
}
]
4.3 查看历史消息
协议: http
方法: GET
路径: message/
|
参数 |
参数说明 |
参数样例 |
|
user_chat_id |
所属会话ID；获取某个会话的消息 |
1 |
|
start_time |
查历史消息的起始时间；给出start_time则查看历史消息 |
2020-04-26 08:04:52 |
|
offset |
从哪一条消息开始展现；可选；默认0 |
5 |
|
limit |
每页展示几条消息；可选；默认5 |
3 |
地址样例：http://127.0.0.1:8000/message/
备注：需要在headers中加入成功登录获取的token
成功返回样例（json）：
{
"status": 200,
"msg": "获取该会话的消息成功",
"all_page_num": 4,
"data": [
{
"id": 9,
"send_time": "2020-04-26 07:51:53.056864",
"message": "this is 222",
"type": 0,
"status": 1,
"chat": 1,
"from_user": 6,
"to_user": 5
},
{
"id": 8,
"send_time": "2020-04-26 07:49:40.156990",
"message": "this is 111",
"type": 0,
"status": 1,
"chat": 1,
"from_user": 5,
"to_user": 6
},
{
"id": 7,
"send_time": "2020-04-26 07:26:58.566607",
"message": "what are you doing now?",
"type": 0,
"status": 1,
"chat": 1,
"from_user": 5,
"to_user": 6
}
]
}
4.4 发送消息
协议: http
方法: POST
路径: message/
|
参数 |
参数说明 |
参数样例 |
|
to_user_phone |
以电话标识目标用户 |
13588888888 |
|
message |
消息内容 |
你好！忙啥呢？ |
地址样例：http://127.0.0.1:8000/message/
备注：需要在headers中加入成功登录获取的token
成功返回样例（json）：
{
"status": 200,
"msg": "发送消息成功"
}
5 实时发送消息API(websocket)
使用websocket实时发送和接收消息。
协议: websocket
路径: ws/chat/
地址样例：ws://127.0.0.1:8000/ws/chat/?token=140a1bf3e4909c8a6a8dc070ff13c807aec23bb4
备注：需要在参数中加入成功登录获取的token
websocket连接：通信双方用户都要连接websocket，如果目标用户没有连接ws，则只有离线消息写入，没有实时消息。
发送数据（json格式）：
|
字段 |
字段说明 |
字段值样例 |
|
message |
消息内容 |
Hello!this is 13910911111 |
|
to_user_id |
目标用户电话 |
13588888888 |
发送数据（json格式）样例：
{"message":"Hello!this is 13910911111","to_user_id":"13588888888"}
对方用户会马上收到消息，接收数据（json格式）样例：
{
"message": "Hello!this is 13910911111"
}
