API设计准则

 

1、Web API的设计规范
1.1restfull协议 （标准的操作类型， 层级资源关系设计，分页设计、属性排序、筛选设计等）
1.2良好接口设计
1.2.1客户易学习，有完善的文档及提供尽可能多的示例和可copy－paste的代码(sample code)；
1.2.2客户易使用，没有难理解或易误解的细节，易于学习。灵活的API允许按字段排序、可自定义分页、 排序和筛选等；
1.2.3一个完整的API意味着被期望的功能都包含在内，同时API个数尽可能少，如果一个API可以暴露也可以不暴露，那么就不要暴露他，等到用户真正有需求的时候再将它成为一个公开接口也不迟；
1.2.4API设计需要考虑向后兼容，第一版的接口需要尽量简单，后续的新需求可以通过扩展的方式完成；
1.2.5不同系统的接口设计风格需要保持一致；
1.3添加版本号，api改动升级可以通过不同版本号进行区分，服务上最好不要强迫客户立即升级。版本号可以直接添加在url上；
1.4错误码规范，方便客户调试与问题排查。可以这么来做：首先区分客户端和服务端的错误码；其次区分不同微服务之间的错误码；最后区分不同类型的错误码。
1.5AK/SK鉴权和SSL加密。使用AK/SK的方式进行鉴权，适用于私有云这样的场景，它的特点是集成简单，运行效率高；但在公有云场景下，可以考虑使用SSL进行加密，它能较好的防止黑客的网络攻击，升防护等级。