接口文档参考示例

# 接口文档参考示例

用户登录 - POST /api/login/

开发者：骆昊

版本号：v1

最后修改时间：

接口说明：登录成功后，会生成或更新用户令牌（token）。

使用帮助：测试数据库中预设了四个可供使用的账号，如下表所示。

用户名用户口令角色

jackfrued 123456 管理员

wangdachui 123123 普通用户

hellokitty 123123 房地产经理人

wuzetian 123456 房东

请求参数：

参数名类型是否必填参数位置说明

username 字符串是消息体用户名

password 字符串是消息体用户口令

响应信息：
- 登录成功：
```
{
    "code": 30000,
    "message": "用户登录成功",
    "token": "f83e0f624e2311e9af1f00163e02b646"
}
```
  1
  2
  3
  4
  5
- 登录失败：
```
{
    "code": 30001,
    "message": "用户名或密码错误"
}
```
  1
  2
  3
  4
发送短信验证码 - GET /api/mobile_code/{国内手机号}/

开发者：骆昊

版本号：v1

接口说明：给指定手机号发送短信验证码的接口，手机号必须是国内手机号，作为路径参数写到URL中。接口显示短信发送成功时，指定的手机号并不会收到短息，因为使用的三方短信平台赠送的测试短信已经用完了。

使用帮助：国内手机号暂不支持国际区号。

请求参数：暂无。

响应信息：
- 请求成功：
```
{
    "code": 10001,
    "msg": "短信验证码发送成功"
}
```
  1
  2
  3
  4
- 两次请求间隔小于60秒：
```
{
    "code": 10002,
    "msg": "请不要在60秒以内重复发送手机验证码"
}
```
  1
  2
  3
  4
- 手机号无效：
```
{
    "code": 10003,
    "msg": "请提供有效的手机号"
}
```
  1
  2
  3
  4
- 短信服务平台故障：
```
{
    "code": 10004,
    "msg": "短信服务暂时无法使用"
}
```
  1
  2
  3
  4

用户名	用户口令	角色
jackfrued	123456	管理员
wangdachui	123123	普通用户
hellokitty	123123	房地产经理人
wuzetian	123456	房东

参数名	类型	是否必填	参数位置	说明
username	字符串	是	消息体	用户名
password	字符串	是	消息体	用户口令

获取所有省级行政单位 - GET /api/districts/

开发者：骆昊

版本号：v1

接口说明：暂无。

使用帮助：暂无。

请求参数：暂无。

响应信息：

[
    {
        "distid": 110000,
        "name": "北京市"
    },
    {
        "distid": 120000,
        "name": "天津市"
    }
]

1
2
3
4
5
6
7
8
9
10

获取指定行政单位详情及其管辖的行政单位 - GET /api/districts/{行政单位编号}/

开发者：骆昊

版本号：v1

接口说明：通过URL参数指定行政单位编号，如果行政单位编号为省级行政单位编号，则返回该省以及该省所辖市级行政单位的信息；如果行政单位编号为市级行政单位编号，则返回该市以及该市所辖区县的信息；如果行政单位编号为区县一级行政单位编号，则返回该区县的信息，下级行政单位cities属性值为[]。

使用帮助：数据库中除四川省外其他行政单位的“intro”数据都没有录入，该字段可能为空字符串。

请求参数：暂无。

响应信息：

{
    "distid": 510000,
    "name": "四川省",
    "intro": "位于中国西南地区内陆，东连重庆，南邻云南、贵州，西接西藏，北界陕西、甘肃、青海，四川省总面积48.6万平方千米，省会成都。截至2018年底，四川省下辖18个省辖市，3个自治州，17个县级市，108个县，4个自治县，54个市辖区。",
    "cities": [
        {
            "distid": 510100,
            "name": "成都市"
        },
        {
            "distid": 510300,
            "name": "自贡市"
        },
        {
            "distid": 510400,
            "name": "攀枝花市"
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

获取热门城市 - GET /api/hotcities/

开发者：骆昊

版本号：v1

接口说明：暂无。

使用帮助：暂无。

请求参数：暂无。

响应信息：

[
    {
        "distid": 110100,
        "name": "北京市"
    },
    {
        "distid": 120100,
        "name": "天津市"
    },
    {
        "distid": 130100,
        "name": "石家庄"
    }
]

1
2
3
4
5
6
7
8
9
10
11
12
13
14

分页获取房地产经理人信息 - GET /api/agents/

开发者：骆昊

版本号：v1

接口说明：经理人姓名按照前缀模糊匹配的方式进行处理；经理人服务星级是指经理人服务星级不得低于该星级；经理人是否持证只有0（未持证上岗）和1（持证上岗）两个选项。三个参数代表的筛选条件之间是而且的关系。返回结果为分页之后的房地产经理人信息。

使用帮助：暂无。

请求参数：

参数名	类型	是否必填	参数位置	说明
name	字符串	否	查询参数	经理人姓名
key	字符串	否	查询参数	经理人服务星级
cert	字符串	否	查询参数	经理人是否持证
page	整数	否	查询参数	页码，默认值为1
size	整数	否	查询参数	页面大小，默认值为5，最大值不超过50

响应信息：

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "agentid": 6,
            "estates": [
                {
                    "estateid": 11,
                    "name": "灵芝新村",
                    "hot": 20
                }
            ],
            "name": "肖利丽",
            "tel": "13040813886",
            "servstar": 4,
            "realstar": 4,
            "profstar": 4,
            "certificated": false
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

新增房地产经理人 - POST /api/agents/

开发者：骆昊

版本号：v1

接口说明：暂无。

使用帮助：需要登录且拥有管理员权限，用户身份令牌在请求头中提供。

请求参数：

参数名	类型	是否必填	参数位置	说明
name	字符串	是	消息体	经理人姓名
tel	字符串	是	消息体	经理人手机
servstar	整数	否	消息体	默认值0
realstar	整数	否	消息体	默认值0
profstar	整数	否	消息体	默认值0
certificated	整数	否	消息体	默认值0
token	字符串	是	请求头	用户身份认证令牌

响应信息：

新增成功 - 状态码201：

{
    "agentid": 8,
    "estates": [],
    "name": "孙小美",
    "tel": "13800991234",
    "servstar": 0,
    "realstar": 0,
    "profstar": 0,
    "certificated": false
}

1
2
3
4
5
6
7
8
9
10

未提供身份认证信息 - 状态码401：

{
    "detail": "不正确的身份认证信息。"
}

1
2
3

当前用户没有操作权限 - 状态码403：

{
    "detail": "您没有执行该操作的权限。"
}

1
2
3

编辑房地产经理人信息 - PUT /api/agents/{房地产经理人编号}/

开发者：骆昊

版本号：v1

接口说明：暂无。

使用帮助：需要登录且拥有管理员权限，用户身份令牌在请求头中提供。

请求参数：

参数名	类型	是否必填	参数位置	说明
name	字符串	是	消息体	经理人姓名
tel	字符串	是	消息体	经理人手机
servstar	整数	否	消息体	默认值0
realstar	整数	否	消息体	默认值0
profstar	整数	否	消息体	默认值0
certificated	整数	否	消息体	默认值0
token	字符串	是	请求头	用户身份认证令牌

响应信息：

更新成功 - 状态码200：

{
    "agentid": 1,
    "estates": [
        {
            "estateid": 1,
            "name": "今日家园",
            "hot": 20
        },
        {
            "estateid": 2,
            "name": "翡翠园",
            "hot": 30
        },
        {
            "estateid": 3,
            "name": "万科城市花园",
            "hot": 22
        }
    ],
    "name": "袁晓梦",
    "tel": "158173555285",
    "servstar": 5,
    "realstar": 4,
    "profstar": 3,
    "certificated": true
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

未提供身份认证信息 - 状态码403 - 与新增类同
当前用户没有操作权限 - 状态码403 - 与新增类同

删除房地产经理人 - DELETE /api/agents/{房地产经理人编号}/

开发者：骆昊

版本号：v1

接口说明：暂无。

使用说明：暂无。

请求参数：

参数名类型是否必填参数位置说明

token 字符串是请求头用户身份认证令牌

响应信息：
- 删除成功 - 状态码204
- 未提供身份认证信息 - 状态码403 - 与新增类同
- 当前用户没有操作权限 - 状态码403 - 与新增类同

参数名	类型	是否必填	参数位置	说明
token	字符串	是	请求头	用户身份认证令牌

分页获取楼盘信息 - GET /api/estates/

开发者：骆昊

版本号：v1

使用帮助：暂无。

请求参数：

参数名	类型	是否必填	参数位置	说明
name	字符串	否	查询参数	楼盘名（模糊匹配）
dist	字符串	否	查询参数	楼盘所在地区编号
page	整数	否	查询参数	页码，默认值为1
size	整数	否	查询参数	页面大小，默认值为5，最大值不超过50

响应信息：

{
    "count": 16,
    "next": "https://120.77.222.217/api/estates/?page=2",
    "previous": null,
    "results": [
        {
            "estateid": 6,
            "district": {
                "distid": 440303,
                "name": "罗湖区"
            },
            "agents": [
                {
                    "agentid": 2,
                    "name": "杨伟",
                    "tel": "13352939550",
                    "servstar": 3
                },
                {
                    "agentid": 4,
                    "name": "郭志鹏",
                    "tel": "13686810707",
                    "servstar": 4
                }
            ],
            "name": "幸福里",
            "hot": 300,
            "intro": ""
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

新增楼盘 - POST /api/estates/

开发者：骆昊

版本号：v1

接口说明：暂无。

使用帮助：需要登录且拥有管理员权限，用户身份令牌在请求头中提供。

请求参数：

参数名	类型	是否必填	参数位置	说明
name	字符串	是	消息体	楼盘名称
hot	整数	否	消息体	楼盘热度，默认值0
intro	字符串	否	消息体	楼盘介绍，默认值空字符串
distid	整数	是	消息体	楼盘所在地区编号
token	字符串	是	请求头	用户身份认证令牌

响应信息：

新增成功 - 状态码201：

{
    "estateid": 17,
    "district": 510107,
    "name": "世纪锦苑",
    "hot": 100,
    "intro": ""
}

1
2
3
4
5
6
7

未提供身份认证信息 - 状态码403：

{
    "detail": "请提供有效的身份认证信息"
}

1
2
3

当前用户没有操作权限 - 状态码403：

{
    "detail": "You do not have permission to perform this action."
}

1
2
3

编辑楼盘信息 - PUT /api/estates/{楼盘编号}
删除楼盘信 - DELETE /api/estates/{楼盘编号}
获取所有户型信息 - GET /api/housetypes/
新增户型 - POST /api/housetypes/
编辑户型信息 - PUT /api/housetypes/{户型编号}
删除户型 - DELETE /api/housetypes/{户型编号}

分页获取房源信息 - GET /api/houseinfos/

开发者：骆昊

版本号：v1

接口说明：暂无。

使用帮助：暂无。

请求参数：

参数名	类型	是否必填	参数位置	说明
title	字符串	否	查询参数	房源标题关键词
dist	整数	否	查询参数	楼盘所在地区编号
min_price	整数	否	查询参数	价格区间下限
max_price	整数	否	查询参数	价格区间上限
type	整数	否	查询参数	户型编号
page	整数	否	查询参数	页码，默认值为1
size	整数	否	查询参数	页面大小，默认值为5，最大值不超过50

响应信息：

{
    "count": 7,
    "next": "http://localhost:8000/api/houseinfos/?dist=440303&page=2",
    "previous": null,
    "results": [

    ]
}

1
2
3
4
5
6
7
8

查看房源详情 - GET /api/houseinfos/{房源编号}
新增房源 - POST /api/houseinfos/
编辑房源信息 - PUT /api/houseinfos/{房源编号}
删除房源 - DELETE /api/houseinfos/{房源编号}
随机获取指定数量的房源标签 - GET /api/tags/
分页查看房源标签 - GET /api/tags/
新增房源标签 - POST /api/tags/
删除房源标签 - DELETE /api/tags/{房源编号}
查看房源的图片 - GET /api/houseinfos/{房源编号}/photos/
为房源添加图片 - POST /api/houseinfos/{房源编号}/photos/
删除房源图片 - DELETE /api/houseinfos/{房源编号}/photos/{图片编号}

← 常见反爬策略及应对方案网络API接口设计 →