API接口设计要考虑的因素

1、接口版本化

生产环境中，若是没有版本控制的程序变动会致使调用接口的相关方频繁的跟着变动，假设相关方没有及时的跟着变动，那么系统就会报错，从而影响到用户的使用及体验，使其对整个系统的运营都是不利的，接口对接的难度也会不断的加大。

若是接口可以有版本的控制，则升级系统的主动权就掌握在相关方，这样当有新版本的程序发布时旧版本的业务逻辑不会受到影响，从用户感知上也受到的影响就比较小，相关方也能够根据自身的条件是否要升级版本。

2、接口面向的应用场景

在对接口进行设计时，咱们还要考虑接口是面向web前端开发仍是手机app开发，或者服务端开发。不一样的应用场景接口整体规划是不一样的（例如：当咱们的接口是提供给web前端或APP端使用时，接口安全验证咱们能够采用jwt、oauth2.0等，若是咱们的接口是提供给后端服务使用时，那么我能够采用token机制）。

3、请求参数的规范性及处理的统一性

请求参数的规范性意思就是说，接口要以什么样的方式来接收参数。是统一使用json的方式接收呢仍是xml或者form表单方式接收。

在开发接口应该统一在一个地方进行对参数的接收、校验等操做。为了保证参数的完整性，咱们能够考虑新增签名验证等处理。

4、返回数据类型、返回码及信息提示的规范性

返回给客户端的数据类型应该要统一化（例如：咱们统一以json的形式进行返回，或者是统一以xml的形式返回）。

不一样的接口设计模式返回码也会不一样，若是使用如今很是火也比较流行的restfull风格那么就应该要准许restfull风格的返回码规定。若是是统一采用自定返回码的话在设计返回码时，应该要学会针对不一样的业务处理模块对返回码进行分段处理（例如：系统基础管理咱们使用10000-10050，用户管理则就应该要从10051到10100，……），针对不一样业务模块咱们要预留足够的返回码，由于后期针对该模块的开发可能还会有其它业务的扩展或者调整等问题。返回码分段处理的一个好处就是方便调用接口的相关方可以很快的定位到错误是属于哪个部分，同时也方便接口开发人员定位接口错误在哪一个地方。

除了返回码，咱们对接口返回的错误提示信息和接口调用成功的提示信息都应该明确，提示到点上。固然有些错误信息多是自身API的bug或者服务器的问题等因素，这样的话咱们就应该要转化一下提示不能把API自身问题暴露给接口调用相关方，这样会致使接口的安全性等问题。

5、接口安全验证及权限的控制

接口并非每一个操做者都能请求访问的，因此咱们要为接口提供一个安全验证，就像用户登陆系统同样，没有在咱们系统注册的合法用户咱们是不容许请求访问的。那么咱们要如何对接口进行安全验证呢？其实针对不一样的应用场景咱们的接口安全验证也不同（例如：当咱们的接口是提供给web前端或APP端使用时，接口安全验证咱们能够采用jwt、oauth2.0等，若是咱们的接口是提供给后端服务使用时，那么我能够采用token机制）。

权限的控制是指针对不一样的用户群体，咱们要分配不一样的权限（例如：超级管理员能够操做全部接口，普通用户只容许操做部分接口），这里除了针对用户群体咱们能够针对不一样的调用接口的相关方（这里的相关方是指调用接口的应用）进行权限控制。

6、接口调用频率的控制

对接口的调用频率进行控制从另外一方面来说也是为了接口的安全性及接口的可维护性，固然这里是否要对接口访问次数进行控制仍是取决于接口针对不一样的应用场景，有些接口的设计是不须要限制调用频率的，而有些接口则对接口调用是要进行严格控制的（例如：你们熟知的微信公众号的开发就是对接口的调用频率进行限制，而且针对不一样的场景及用户群体限制的频率也不同）。

7、请求接口日志的记录

咱们应该要为接口请求作一下日志的记录，这样咱们后期维护接口时则会大大下降维护成本。并且还能够针对日志进行相关的统计处理。

8、接口文档的可读性

接口文档的可读性很是重要，一个接口开发出来并非真正的完成，若是别人不会使用你的接口，那么你的接口开发出来也是没有用的，好多程序员很是的不重视接口文档撰写及接口文档可读性，写出来的文档就像一本天书看着就头大。好的文档应该让人一看就知道如何调用，如何规避一些坑，简单明了等等。这里我介绍两个比较好的接口管理可视化工具给你们参考一下swagger和阿里巴巴的rap。