一.协议
1.【推荐】API与用户的通信协议，总是使用HTTPS协议。
二.域名
1.【强制】正式环境下API的请求地址应该使用域名，不应使用IP地址；
2.【推荐】应尽量将API部署在专用域名下，如：
https://api.example.com/
如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。
https://example.com/api/
三.HTTP方法
1.【强制】参数名与参数值拼装起来的URL长度小于1024个字符时，可以用GET发起请求；参数类型含byte[]类型或拼装好的请求URL过长时，必须用POST发起请求。所有API都可以用POST发起请求。
四.API命名(URI路径)
1.【强制】API 命名应该采用约定俗成的方式，保持简洁明了，uri路径包括uri参数不能出现大写字母，单词之间使用下划线(_)分割。
2.【推荐】避免层级过深的URI，尽量使用查询参数代替路径中的实体导航，如：
正例：- GET /comments/get?user_id=1234&comment_id=1 (获取用户ID为1234的评论ID为1的单个评论)
反例：- GET /users/1234/comments/1 (获取用户ID为1234的评论ID为1的单个评论)
3.【推荐】可以通过在URL路径增加(HTTP)动词来对服务器资源进行CRUD，而不是直接通过HTTP方法(GET\PUT\POST\DELETE)。如：
/gettoken 获取token
/user/get 获取用户信息
/user/create 创建用户
/user/update 更新用户
/user/delete 删除用户
/user/list 获取用户列表
五.过滤信息
1.【推荐】优雅的设计条件过滤，排序等传入参数形式；
以下是一些常见的参数：
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?sortby=name&order=desc：指定返回结果按照哪个属性排序，以及排序顺序。
?user_type=1：指定筛选条件
2.【推荐】对于一些常用的、复杂的查询，可以映射到一个新的API。(类似快捷方式)
如：-GET /orders/get?status=closed&sortby=created_at&order=desc
快捷方式：-GET /orders/get_recently_closed
3.【推荐】API支持选择查询字段的能力
说明：一些情况下，我们只需要在列表中查询几个有标识意义的字段，我们不需要从服务端把所有字段的值都请求出来，所以需要支持API选择查询字段的能力，这也可以提到网络传输性能和速度：
GET /cars?fields=manufacturer,model,id,color
六.请求参数
1.【推荐】API参数应包含公共参数和业务参数，公共参数保存通用基本的参数，每次接口调用都要传入。公共参数可参考如下：
七.返回结果
1.【强制】接口返回的数据体最少包含errcode(错误代码),errmsg(错误信息)，错误代码用于错误追查，错误文本信息用于展示给用户；
八.错误处理
1.【强制】不要发生了错误但给2xx响应，客户端可能会缓存成功的http请求
2.【强制】如果状态码是4xx，就应该向用户返回错误信息，错误信息应该准确、简明、扼要，可引导用户进行下步操作。
九.签名算法
为了防止API调用过程中被黑客恶意篡改，调用任何一个API都需要携带签名，服务端根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。(具体签名算法待讨论，下面引用支付宝的签名算法作为参考)
1.筛选并排序
获取所有请求参数，不包括字节类型参数，如文件、字节流，剔除sign字段，剔除值为空的参数，并按照第一个字符的键值ASCII码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值ASCII码递增排序，以此类推。
2.拼接
将排序后的参数与其对应值，组合成“参数=参数值”的格式，并且把这些参数用&字符连接起来，此时生成的字符串为待签名字符串。
例如下面的请求示例，参数值都是示例，开发者参考格式即可：
REQUEST URL: https://openapi.alipay.com/gateway.do
REQUEST METHOD: POST
CONTENT:
app_id=2014072300007148
method=alipay.mobile.public.menu.add
charset=GBK
sign_type=RSA2
timestamp=2014-07-24 03:07:50
biz_content={"button":[{"actionParam":"ZFB_HFCZ","actionType":"out","name":"话费充值"},{"name":"查询","subButton":[{"actionParam":"ZFB_YECX","actionType":"out","name":"余额查询"},{"actionParam":"ZFB_LLCX","actionType":"out","name":"流量查询"},{"actionParam":"ZFB_HFCX","actionType":"out","name":"话费查询"}]},{"actionParam":"http://m.alipay.com","actionType":"link","name":"最新优惠"}]}
sign=e9zEAe4TTQ4LPLQvETPoLGXTiURcxiAKfMVQ6Hrrsx2hmyIEGvSfAQzbLxHrhyZ48wOJXTsD4FPnt+YGdK57+fP1BCbf9rIVycfjhYCqlFhbTu9pFnZgT55W+xbAFb9y7vL0MyAxwXUXvZtQVqEwW7pURtKilbcBTEW7TAxzgro=
version=1.0
则待签名字符串为：
app_id=2014072300007148&biz_content={"button":[{"actionParam":"ZFB_HFCZ","actionType":"out","name":"话费充值"},{"name":"查询","subButton":[{"actionParam":"ZFB_YECX","actionType":"out","name":"余额查询"},{"actionParam":"ZFB_LLCX","actionType":"out","name":"流量查询"},{"actionParam":"ZFB_HFCX","actionType":"out","name":"话费查询"}]},{"actionParam":"http://m.alipay.com","actionType":"link","name":"最新优惠"}]}&charset=GBK&method=alipay.mobile.public.menu.add&sign_type=RSA2×tamp=2014-07-24 03:07:50&version=1.0
3.调用签名函数
使用各自语言对应的SHA256WithRSA(对应sign_type为RSA2)或SHA1WithRSA(对应sign_type为RSA)签名函数利用私钥对待签名字符串进行签名，并进行Base64编码。
4.把生成的签名赋值给sign参数，拼接到请求参数中。
十.其他
1.API的身份认证应该使用OAuth2.0框架。
2.服务器返回的数据格式，应该尽量使用JSON，避免使用XML。
3.所有的请求和响应数据编码皆为utf-8格式。
4.所有的请求和响应数据参数命名应为小写字母，单词拼接使用下划线(_)。
