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

You may also like...

Leave a Reply

Your email address will not be published. Required fields are marked *