API接口设计规范

       在项目中API接口开发是我们逃不过的，我们也在不停的写接口、调用接口，设计一个API接口看似很简单，但是要设计一个完美的API接口也不容易。

        设计API接口最重要的就是要让调用方看得懂、轻松调用，同时在提供方能够保证安全性、容易扩展以及项目迭代的兼容性。因此在设计时既要规范也要遵循行业内的约定俗成，最首先的要遵循RESTFUL规范，不能自己随意创造一套自己的规范，这会给调用方添加对接成本。(除非你已经做到行业内的标杆，让大家都跟随于你，这个就另外了)。

        那么设计一个好的API接口需要遵循哪些要素呢？

1. 定义API接口版本

        在实际项目中，项目不可能是固定不变的，每个项目都是在不断的根据用户需求进行迭代更新，而你的API在迭代更新时需要考虑到会有不同的调用方，有些调用方并不会随着你的迭代进行迭代，在迭代时又不可能直接修改API接口，需要做到向下兼容，所以这时就需要添加版本控制，每一次迭代都是在原有版本上的升级，如 1.0 -> 2.0 -> 3.0 。在升级到2.0的同时也需要满足1.0版本也能正常使用。

        设计的API版本可以放在调用的URL中或者在Header头部中添加version版本号。

        例如：

        Https://api.xxx.com/{1.0}/action

        headers:{ version: '1.0' }    

2. 请求参数和返回数据的规范性

        这里也是RESTFUL规范里的要求，对请求的参数和返回的数据进行定义，是按照json或xml格式进行传输，同时在你提供的所有接口中都统一按照相同的数据格式。

3. 定义API接口的应用场景

        这里的应用场景指的是提供给web端、app端或者是后端服务器，不同的应用场景对安全验证的方式也不一样。web前端或APP端时安全验证可以采用jwt、oauth2.0等，如果是提供给后端服务端时可以采用token机制。

4. 安全验证及权限的控制

        我们的API接口一般都不会是面向所有客户端，大部分我们都需要进行注册或者添加进我们的白名单才能进行调用，因此就需要对调用方进行安全验证，安全验证方式如３所说，对不同的应用场景其验证的方式也不一样。同时在调用API时一般都需要带有用户信息，而不同的用户可能被赋予的权限也不同，也需要做权限的控制。

5. 设置调用频率

        如果不想你的API接口被别人恶意调用的话，你就得设置调用频率，这是对安全性的一重保障，接口调用频率的多少最终取决于你得接口针对的是什么样的应用场景，例如：登录接口，可能频率就会很低，一分钟内只允许调用3-5次。

6. 请求接口日志

        日志的主要作用就是排查异常，日志能够保留下当时发生的事，这样就可以对异常进行场景重现，找到问题，可以大大降低维护的成本。

7. 完善接口文档

        设计出来的API接口主要就是给调用方调用使用的，如果没有文档调用方就无法进行调用，有文档但是看不懂也是徒劳，也会增加调用的成本，因此接口文档的规则就是要全面、简洁、易懂、符合API接口规则。

8. API接口沙盒环境

        调用方在开发时并不会使用实际的数据，他们在开发时也需要进行测试，有时候测试数据可能会很多，总不能够让所有调用方在你的正式环境下进行测试留下一堆的脏数据吧，所以提供沙盒环境也是很重要的，同时沙盒环境要确保和正式环境是一致的。

        以上就是个人总结的在设计API接口时的规范，也期望大家都能够设计出人人都能看得懂的API接口，让API接口变得不再困难。