其他分享
首页 > 其他分享> > 即时通信软件后端API文档

即时通信软件后端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"

}

标签:status,http,样例,API,文档,user,msg,通信软件,id
来源: https://www.cnblogs.com/djlbolgs/p/12816779.html