REST API设计的五个小建议

一个很好的API设计是非常难的，他需要维护向后的兼容，有效的测试，处理API的升级等等。希望这篇文章能给你以帮助。

毫无疑问，API已经成为系统信息交互的一个重要渠道，同时也是系统内部各个模块有机组成的重要部分。

这篇文章，就和大家分享一下我在REST API设计和实现中所遵循的一些建议：

• 能使用客户端的SDK就不要自己重写代码

假如服务供应商有自己的SDK，那么我们就尽量去使用他提供的SDK，而不要在本地REST调用上面写自己的库。一个很好的例子就是，当你使用亚马逊的网络服务时可以选择的AWS SDK。直接选择使用AWS SDK使得我的团队节约了很多时间去写我自己的逻辑处理安全，网络超时，重试，回调等等问题。

因为这些SDK都是由服务商进行维护的，开发者不需要处理测试，集成，修改来支持新的API端口。很多SDK都是开源的，并且基于标准的接口（REST, WebSocket，gRPC等），这些都能够很快地集成。

API SDK最大的问题就是可靠性和你选择的编程语言的支持。这种情况下，开发者就需要开发自定义的REST的客户端。我总是推荐开发者使用一个独立的Maven项目来设计和实现它。并且把它发送商业的git repo中，写好文档，在你组织内部可以共享。

• 使用Swagger来做文档

Swagger对API开发者来说实在是太重要了，尤其是对那些具有不同背景的开发者来说。它也是一个最优秀的开发框架而且对开发者来说很简单。作为开发者来说，我可以很方便地执行API并且做相关的测试，而不需要看很多文档，读很多文字。作为API的使用者，你可以搞懂API，包括他的参数啊，所希望的payload的模式啊之类。

我并不是说一个有更具体信息的的文档是没有价值，只是我发现这些文档总是不能及时更新。所以，在我看来，使用Swagger来完成文档，并且帮助别的开发者更开的开始集成是一个很好的选择。

• 对端口的设计遵循一个标准的方法

当设计一个API的时候，很多开发者都不遵循端口设计的标准，或者不根据HTTP的操作来定义接口。网上其实有很多资料讲这个问题，大家可以参考最后参考链接。

下面是一些我严格遵守并要求我的开发者也遵守的规则：

1. 不要在API的定义中混入大小写。比如不要使用/users/userId，而使用/users/{id}。不要使用POST “/deleteUser/userId”，而使用DELETE “users/{id}”。
2. 在URL中总是使用版本的控制，比如把”api/v1/”作为一个必须的部分。
3. 把https作为一个客户端默认连接的选项。
4. 对payload做一个校验，并且在代码的第一步中执行这个。不要把它放到后面，然后要catch exception的方式来处理。
5. 处理升级

想象一下，你的服务使用API来传递一些数据，然后他突然不工作了。通过很多email的讨论，message的传递，你终于搞清楚了，oh，原来在payload上有一个改动，需要一个额外的强制部分。这个问题就是API升级了，但是并不向前兼容。

这类的问题其实是可以在早起使用任何CI的流程来发现的，但是作为一个API的开发者，在你进行修改之前，你需要好好想想怎样处理已经存在的客户端。比如，你加入了一个新的必须的部分，那么要不使用一个默认的值，要不定义一个新的版本，比如/api/v2等等。

• 测试

不要只做功能性测试，你还需要考虑压力测试。你需要知道服务器每分钟能处理多少个API的调用。当网络latency增加时，响应的时间是多少。许多商业化的客户，他们的数据中心都是全球部署的，或者使用的是多region的云环境。假如你可以向客户提供一个基准数据，比如你把API的服务部署在美西，然后在美东，印度，澳大利亚客户端调用的时间。

我比较倾向于使用一个API的测试工具，比如Postman，Apach JMeter而不是自己写一个新的。他们不仅节约时间，而且也允许把check in到git中的模板导出。

• 总结

一篇文章肯定不能把所有的好的建议都写出来，但还是希望你能够从中学到一些什么。我相信，API开发其实和其它软件开发一样，也有很多特殊的领域值得我们去创新。

原文地址：https://dzone.com/articles/my-5-tips-for-better-restapi-design