api.md

API接口规范

后端同学给前端同学提供接口时，建议使用http://fe.superjia.com:8888/ 平台编写。

接口定义

标题

接口的说明，尽量简短明了。

如：订单列表

URL

接口的请求地址，注意：以斜杠“/”开头。

如：/order/list

Method

接口的请求方法：可以是get，post，put，delete。

接口分类

如果一个项目API列表中有很多记录，建议将接口分到相应的接口分类中。

如：房源宝企业号下：新增房源，房源查询，我的信息等

请求的数据格式

请求参数，根据请求的参数书写。 注意：如果后端是List，则可以写成数组，或者以“,”分隔的字符串， 如：[2, 1, 1]或”2,1,1”。

如果请求的参数值为null或undefined或空白，最好都不传到后端。

如：{
  "estateName": "小区名称",
  "rooms": [2, 1, 1],
  "pageSize": 10,
  "pageIndex": 5
}

返回的数据格式

返回的数据格式包括。

固定属性名：

status: 返回状态，1：成功，其他值表示失败
msg: 返回消息
data：返回对象{}或null。

如：{
  "status": 1,
  "msg": “成功",
  "data": {

  }
}

常规属性名推荐：

data内的对象建议使用如下属性名：

total：数字，记录总数
end：boolean，是否是最后一页；
datas：数组（如果是空数组就返回空数组[]）。

如：{
  "status": 1,
  "msg": “成功",
  "data": {
    "total": 30,
    "end": false,
    "datas":[]
  }
}

各业务线统一自己的属性名

前后端尽量统一使用相同的属性名描述同一个意思
如：区域名称
  // good
    areaName
  // bad
    fieldName

修改说明

记录此次修改的主要内容，方便查看修改历史

请求参数添加了areaId，返回值添加了content