如何设计出优秀的API

目前，后台接口开发可以用RESTFull风格，也可以用Web Service、SOAP协议、RPC协议，也可以用HTTP协议；可以用短连接，也可以使用长连接。如果我们希望继续进行划分，还可以分为同步或异步、单个或批量、是否有SDK包、内部接口还是开放接口平台等。

评判维度

1.API接口应该是需要定义一定的规范，例如简短易记，通俗易懂等，从程序的角度来说，API应该遵循行业规范，在调用时不需要做特殊化处理，有利于复用已有的代码或工具。

2.API发布上线之后，要根据真实用户的反馈或者业务发展的需要进行调整，这些调整必须尽量不影响用户。要么提供多版本支持，要么给用户提供切实可行的更新策略等等。

3.对外公开的API存在被攻击的风险，以及无法准确预估的访问量等，一个好的API必须要有防注入、防篡改、防重放等安全机制，还要在访问量急剧上涨时避免服务挂掉。

URL规范

1.便于输入的URI，简短不冗余。每个WEB API都是一个服务，那下面反例当中的“service”就是冗余的，而且“api”也重复出现了两次，这种冗余都不利于记忆和输入。

反例：http://api.example.com/api/service/users
正例：http://api.example.com/users
复制代码

2.没有大小写混用的URI。HTTP协议（RFC7230）规定：除了模式（schema）和主机名以外，URI的其他信息都要区分字母的大小写。下述两个反例大小写混用，不方便记忆。

反例：http://api.example.com/Users/12345
反例：http://example.com/API/getUserName
复制代码

3.规则统一的URI，确保采用统一的规则和风格，方便用户记忆和使用，易于修改的URI，命名存在可预见的规律，下述正例我们可以很容易猜测改变最后的ID就可以访问其他内容的信息。

正例：http://api.example.com/v1/users/123456
复制代码

规范总结

1.URI最好由名词组成。URI的全称是统一资源定位符（Uniform Resource Identifier），用于标识资源在互联网上的位置，类似于邮寄地址，而地址都是由名词组成的。在名词使用上也有一些需要注意的事项：其一，使用名词复数形式；其二，尽量采用多数API中使用的表示相同含义的单词；其三，通过尽可能少的单词来表示；其四，尽可能不用奇怪的缩略语等。

2.不使用空格及需要编码的字符，例如在URI中使用中文等。

3.使用连接符（-）来连接多个单词，推荐脊柱法：首先，URI里的主机名（域名）允许使用连字符而禁止使用下划线，且不区分大小写。其次，点字符具有特殊含义，为了与主机名的规则保持一致。

脊柱法：http://api.example.com/v1/users/12345/profile-image
蛇形法：http://api.example.com/v1/users/12345/profile_image
驼峰法：http://api.example.com/v1/users/12345/profileImage
复制代码

版本控制

1.咱们在开发的过程中对于版本迭代是无法避免的，但是怎么去做到在各个版本之间做到好的兼容性，不去破坏原有的API避免影响老版本的正常使用，尤其是程序已经上线并且别很多人使用的情况下.

2.您也可以对准备抛弃的老版本用户进行建议升级，不过不提倡直接关闭某个版本或者不对某个版本进行维护，而是在提示用户在未来的某一天这个版本的接口将停止维护与关闭，尽量升级至最新的版本。(可以参考近期Windows对Win7的公告)

3.好的RESTFull会在URL上显示具体的版本号。比较常见的方案是把版本号放在请求的Header中和放在URL上，我比较建议使用第二种方案,这样更加直观与方便

示例:http://api.example.com/v1/*
复制代码

4.版本编号也存在业界规范：语义化版本控制（Semantic Versioning）规范，网站地址：semver.org。版本编号由点号连接的3个数字组成，例如：1.2.3，分别表示主版本编号、次版本编号、补丁版本编号，版本编号的增加遵循下述规则：

1. 在对软件进行不向下兼容的变更时，增加主版本编号；

2. 在对软件进行向下兼容的变更或废除某些特定的功能时，增加次版本编号；

3. 如果软件的API没有发生变更，只是修正了部分bug，则增加补丁版本编号。

状态码

1.当客户端通过API向服务器发出请求时，客户端应该知道反馈，无论是失败，成功还是请求错误。HTTP状态代码是一系列标准化代码，针对HTTP请求的可能会发生的各种情况。服务器应始终返回正确的状态代码。

2.很多人喜欢把错误信息放在返回值中，典型的Code和Message，其实并不好，下面是Http状态码，可以合理利用处理各种请求反馈，将http自身的错误和服务器内部的错误，有一个很好的区分。

接口文档

1.一个程序员的老笑话，程序员最讨厌不写注释的代码和写代码加注释。写文档是无聊的，但必不可少，良好的文档会保存你的理智思考，会避免api消费的很多问题。一个好的文档包括枚举值字典表，所有API接口的请求参数，请求方法，请求路径，返回参数，正确示例与错误示例不可偷工减料。每个请求参数和返回参数必须加注释，不要让别人去猜，文档必须是演进的，一旦进行修改必须及时同步更新文档。

2.尽量不用使用自动生成的文档，但如果你真的这么做了，那一定要保证你检查和校验过这个文档。不要缩减请求和响应的内容，最好就全部展求。在你的文档中有些重点的要加粗。

结尾

今天先分享到这里，如果你觉得有价值，麻烦动动手指点下 「 分享 」按钮，让更多小伙伴可以看到，我也会更加有动力坚持分享。另外，同学我后续还会分享职业规划、应聘面试、技能提升、影响力打造等经验，欢迎 关注 本掘金号 「 _我思故我在 」！