App HTTP API 交互规范

以你之姓@ 2022-07-14 00:30 156阅读 0赞

App产品一般是以版本迭代的方式进行开发，服务端的系统要求高版本兼容低版本，所以做到同一个接口可以支持多个版本的访问。后端使用spring mvc做为Web框架，handler通过Http请求中的uri和header的version属性做为映射条件：@RequestMapping(value = "/member/info",  headers = \{"accept-version=1.0.0"\})。

1. 新版本接口迭代时，应该考虑兼容低版本。

2. 如果新版本中只是添加了一些字段， 对业务影响不大，可在低版本接口中直接添加字段。

3. 如果新版本中修改的字段对低版本影响不大，并且产品和测试确认可以接受，也可在低版本接口中直接修改。

4. 其它情况，一律以新版本接口开发。

公用的参数放到http header中：

<table> 
 <tbody> 
 <tr> 
 <td> 字段名 </td> 
 <td> 字段类型 </td> 
 <td> 是否必需 </td> 
 <td> 描述 </td> 
 </tr> 
 <tr> 
 <td> version </td> 
 <td> String </td> 
 <td> Y </td> 
 <td> 接口版本 </td> 
 </tr> 
 <tr> 
 <td> app-version </td> 
 <td> String </td> 
 <td> Y </td> 
 <td> App版本 </td> 
 </tr> 
 <tr> 
 <td> device </td> 
 <td> Integer </td> 
 <td> Y </td> 
 <td> 设备类型（1：IOS， 2：Android，3：wap） </td> 
 </tr> 
 <tr> 
 <td> device-name </td> 
 <td> String </td> 
 <td> Y </td> 
 <td> 设备名称 </td> 
 </tr> 
 <tr> 
 <td> device-imei </td> 
 <td> String </td> 
 <td> N </td> 
 <td> 设备序列 </td> 
 </tr> 
 <tr> 
 <td> os-version </td> 
 <td> String </td> 
 <td> N </td> 
 <td> 系统版本 </td> 
 </tr> 
 <tr> 
 <td> token </td> 
 <td> String </td> 
 <td> N </td> 
 <td> 包含用户ID,手机号(加密) </td> 
 </tr> 
 <tr> 
 <td> device_id </td> 
 <td> String </td> 
 <td> N </td> 
 <td> 设备推送ID(极光) </td> 
 </tr> 
 </tbody> 
</table>

服务端响应字段(JSON):

<table> 
 <tbody> 
 <tr> 
 <td> 字段名 </td> 
 <td> 字段类型 </td> 
 <td> 描述 </td> 
 </tr> 
 <tr> 
 <td> code </td> 
 <td> Int </td> 
 <td> 接口响应结果(状态) </td> 
 </tr> 
 <tr> 
 <td> msg </td> 
 <td> String </td> 
 <td> 响应信息 </td> 
 </tr> 
 <tr> 
 <td> responseTime </td> 
 <td> Int </td> 
 <td> 响应时间(精确到秒) </td> 
 </tr> 
 <tr> 
 <td> result </td> 
 <td> Object </td> 
 <td> 响应结果(Object) </td> 
 </tr> 
 </tbody> 
</table>

JSON表示:

“code”:”0”,

“msg”:””,

“responseTime”:”147392039842”,

“result”:”\{\\”key\\”:\\”value\\”\}”

CODE 类型

<table> 
 <tbody> 
 <tr> 
 <td> 值 </td> 
 <td> 描述 </td> 
 </tr> 
 <tr> 
 <td> 0 </td> 
 <td> 调用成功 </td> 
 </tr> 
 <tr> 
 <td> -1 </td> 
 <td> 默认的调用失败 </td> 
 </tr> 
 <tr> 
 <td> -10 </td> 
 <td> 接口需要登录才能访问,当前用户未登录 </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 </tbody> 
</table>