API设计 最值得注意的几个问题

API接口设计涉及多个方面，因为开发者一个点的疏忽，就会给调用API用户带来无尽的麻烦和痛苦。下面总结了一些API接口设计这应该注意的问题。

一、规范的命名规则

无论是接口还是参数，命名都应该有意义，让人一目了然。接口调试技巧前提必须放在外网上。

1、服务端return 调试信息，客户端调用并显示结果，

2、在服务端将结果保存成文件在打开文件查看，即日志型调试（或建临时表放在数据库表里）

二、完善的安全机制

安全永远都是首要保障，调用涉及的验证、数据传输等方面都要多思考，尽可能减少漏洞受到非法攻击。如果出现非法攻击，尽快发现原因，进行修复。

三、详细的说明文档

接口文档要清晰、明了，包含多少个接口，每个接口的地址、参数、请求方式、数据交换格式、参数是否必填、编码格式UTF8，返回值等都要写清楚。

四、全面的终端适配

所谓跨平台是指我们的接口要能够支持不同的终端，比如iOS、Android以及桌面软件、网站等。如：不同的终端每页显示的记录数不同。

采用通用的解决方案，比如通信协议就采用最常用的HTTP协议，如果是即时通信，可以采用开放的XMPP协议，做游戏的可以采用可靠的TCP协议，除非TCP不够用了，再采用定制的UDP协议。

数据交换采用xml或者json格式或者webservice等等。总之，要达到的目标就是让不同的端能够很方便的使用你的接口。

五、快速的响应速度

接口应该以最快的速度将数据返回给请求者,要达到的目标就是快，一个页面，秒开最好，超过三秒就需要找找原因了。数据量按需分配，APP客户端需要什么数据就返回什么数据，过多的数据量影响处理速度，最重要的是影响传输效率。

六、定期的版本维护

随着业务的变化，客户端APP和服务器端API都会发生变化，增加新的功能，修改已有的功能。增加功能还好说， 如果是接口需要修改，那么就面临着同一个接口要同时为不同版本的客户端服务的问题。因此，服务器端接口也要做好相应的版本维护。

七、必要的统计功能

在做PC端网站的时候，我们都会给我们的网站加上个统计功能，要么自己写统计系统，要么使用第三方的比如GA。

移动端接口API则需要我们自己实现统计功能，这时就需要我们尽可能多的收集客户端的信息，除了传统的IP、User-Agent之外，还应该收集一些移动 相关的信息，比如手机操作系统，是iOS或Android，都是什么版本，用户使用的网络状况，是2G、3G、4G还是WIFI。客户端APP是什么版 本信息。

八、及时的调用反馈

接口必须提供明确的数据状态信息，不管是成功的，还是失败的，都必须返回给App客户端。

九、通用的数据交换格式

目前，对于接口和客户端的数据交换格式，基本上就是三种，xml和json和webservice，而现在使用json的应该占大多数最麻烦的就是处理Date类型，因为JSON本身没有Date类型，因此，JSON库将Date类型的数据序列化时会转为String。这时，不同环境， 不同平台，以及用不同的JSON解析库，转换后的结果经常会不同。比如，你在开发机上可能得到的结果是”2017-1-1 17:11:11”，但放到服务器后结果却变成了“Jan 1,2017 5:11:11 PM” ，客户端进行反序列化时无疑会失败。后来，我取消了所有Date类型，统一采用时间戳表示，就再没有转化的烦恼了。

另外，接口的开发人员有时候会将一些数据错误地转换为了String，导致客户端使用时因类型错误而异常。例如，本来是数字的1，被转成 了"1"，客户端做运算时就会出错，或用switch判断时也会出错，或其他无法转换的情况发生时；例如，为空时JSON正确地表示应该是null，但如 果转为了String就变成了"null"，那问题就来了，必须排查原因。