统一API格式文档

在一个项目的整体结构之内，总有空间展示个性和匠心……百年之后，我们的技艺或许如今日的土建工程师看待中世纪大教堂建造者使用的技法一样陈旧，但是我们的匠心确会得到尊重。

一、全局说明

• 本文档用于数据平台所有对内，对外合作项目的API规范，之后新项目接口格式都按此规范执行
• 服务端采用了类 RESTFUL 的 API 风格（接口语义化）
• 所有的 GET 请求的 API 数据接口都采用 JSON 格式。标准的接口格式中都包含着 data 字段，业务数据都包含在这个 data 字段中，并且 data 字段恒为对象格式
• 常见错误通过HTTP状态码来返回错误，业务方约定错误通过 code 值返回错误
• 本API格式说明为服务端API规范，中间层转发默认为全透明代理(完全按后端返回格式为准)
• 与前端合作的所有 http(s) 接口需要记录在 swagger接口管理工具中

二、基本概念

• tn : totalNumber => 总条数
• sn : sizeNumber => 分页阈值
• cn : currentNumber => 当前页数
• pn : pageNumber => 总页数
• q : query => 查询参数
• asc: 1/0 => 升序/降序
• code: 业务约定,0为正确,其他为错误
• orderBy: key => 以 key 作为排序参数

需要注意的点

1. 所有资源 ID 对当前接口返回统一命名为 id
2. 数据库操作 下划线 连接所有对外字段，全部改为小驼峰

三、 接口格式规范、数据类型强统一

每一个接口返回的数据格式应该始终一致

• 同一个接口有 data 字段，不管任何情况都应该返回 data 字段

每个字段返回的数据类型应该始终一致

• 字段类型是 数组 就恒为数组，空值时也应该为空数组，不能为空字符串或者 Null
• 字段类型为 字符串 就恒为字符串，空值为""
• 字段类型为 对象 时，空值为null

四、常见的HTTP状态码

200 ok  - 成功返回状态，对应，GET,PUT,PATCH,DELETE. 
201 created  - 成功创建。     
301 move permanently -永久重定向
302 move temporaily  -临时重定向
304 not modified   - HTTP缓存有效。     
400 bad request   - 请求格式错误。     
401 unauthorized   - 未授权。     
403 forbidden   - 鉴权成功，但是该用户没有权限。     
404 not found - 请求的资源不存在     
405 method not allowed - 该http方法不被允许。     
410 gone - 这个url对应的资源现在不可用。     
415 unsupported media type - 请求类型错误。     
422 unprocessable entity - 校验错误时用。     
429 too many request  -请求过多。
500 interal server error  -内部服务错误
501 not implemented -未实现
502 bad gateway -网关报错
503 service unavailable -服务不可用
504 gateway time-out -网关超时

五、举个栗子

GET方法通用返回定义

1. GET 方法请求单条数据返回的标准数据格式：

// response body 
{     
  "code": -1, // 错误状态码     
  "message": "服务器错误,请联系对应RD负责人"  // 错误消息     
  "data": {         
    //数据 Body     
  }   
  // 数据格式强统一,不论单挑数据还是多条数据查询,Data 都是对象. 
}  

2. GET 方法请求多条数据返回的标准数据格式：

// response body  
{      
  "code": 1,      // 错误状态码      
  "message": "服务器错误,请联系对应RD负责人",  // 错误消息      
  "data": {          
    "tn": 999,                            // 多条数据必须返回          
    "cn": 1,                            // 多条数据必须返回          
    "pn": 10,                           // 多条数据必须返回          
    "sn": 100,                          // 多条数据必须返回          
    "q": "xx",                          // 非必须          
    "cacheTime": '2017-07-31 15:41:27'  // 如果做数据缓存的话,是在返回体里做这个还是 Header 头?          
    "items": [{                  
         //单条数据 Body              
    },{ 
         //单条数据 Body           
    }             
     // ...          
    ]      
  }    // 数据格式强统一,不论单挑数据还是多条数据查询,Data 都是对象.  
}   

POST方法通用返回定义

POST 方法操作成功后，返回三个字段。

• code 字段0表示插入成功,其他数字标识错误编号
• message 字段表示代码运行后显示的消息,如:插入成功 插入失败,已有相关名称
• data 内显示新增字段的内建唯一标识码,告诉前端数据插入到了哪里

{         
  "code": 1,      // 错误状态码         
  "message": "服务器错误,请联系对应RD负责人"  // 错误消息         
  "data": {             
    id: 2 //新插入的事件的唯一标识码         
  }     
} 

PUT/DELETE/PATCH/OPTION方法通用返回定义

这四种方法操作成功后,返回两个字段

{         
"code": 0, // 0 表示操作成功, 其它数字表示错误编号         
"message": "数据更新成功!", 
"data": {}     
}