|
|
51CTO旗下网站
|
|
移动端

5招助您设计出更好的REST API

本文将从SDK与文档的使用,向后兼容性的保持,处置升级,有效地开展测试这五个方面,与您讨论REST API设计的各项实践。

作者:陈峻译来源:51CTO|2020-07-10 07:48

【51CTO.com快译】本文将从SDK与文档的使用,向后兼容性的保持,处置升级,有效地开展测试这五个方面,与您讨论REST API设计的各项实践。

毋庸置疑,API已成为了当前在不同系统之间交换信息的实际标准。它往往能够有助于更好地集成某个系统内部各种组件。那么怎样才能设计出更好的API呢?在本文中,我将和您讨论在进行多种REST API设计和实现时,那些值得遵循的良好实践原则。

1.善用各种客户端SDK,而无需自行编写代码

如果服务提供商或创建者已经给出了一套开发工具包(SDK),那么我们就应该在API调用中使用它们,而无需在本机REST调用之上,去重新编写自己的客户端库。此方面的一个最好例子便是与Amazon Web Services交互的AWS SDK。选择使用AWS SDK,不但有助于减缓的团队学习曲线、快速上手,而且能够节省编写有关安全性、网络超时、重试、回退等逻辑事务处理的时间。

此外,由于这些SDK由提供商所维护,因此开发人员无需进行繁琐的测试、修复和更改,即可支持各种新的API节点。如今,大多数SDK不但开源,并且能够支持和快速集成包括REST、WebSocket、以及gRPC在内的各种标准协议。

不过,API SDK的主要缺点是:可用性,以及对您所选编程语言的支持程度。针对此类状况,开发人员有时需要开发自定义的REST客户端。在此,我的经验是:开发人员应将其设计和实现作为一个单独的Maven项目,托管到企业Git存储库中,并配上充分的文档记录,以供组织中的所有内部团队共享使用。

2.巧用文档

上文提到的配套文档,不但对API开发人员,尤其是那些没有任何开发背景的人员而言,是着手开发的基本要素,而且文档往往也是绝大多数现代化开发框架的一个不可或缺的部分。作为开发人员的我,经常可以根据现有的文档,来轻松地执行与API相关的各项测试,而不必临时到浩如烟海的社区或论坛上,去搜索相关资料。通常,API的相关文档能够向使用者介绍API的基本功能、各种参数、以及预期的负载(payload)模型。

当然,我在参与各种项目中也发现,有些文档虽然包含了详尽的内容(包括负载模型的范例),但是其中有些已经滞后于API的当前版本。因此,我在项目中往往会使用Swagger将文件的方法、参数和模型紧密地集成到服务器端的代码之中,让客户端和文件系统的服务器以同样的速度来更新与同步。

3.遵循标准的端点方法

在设计API时,许多开发人员不但容易忽略端点的标准命名法则,而且并未按照HTTP的各种动词定义进行操作。关于此方面的资料,网上有许多,只要你愿意花时间搜,一定能找到不少。下面,我分享一下自己一直严格遵守,同时也要求部门内开发人员持续遵循的几种方法:

  • 不要在端点中混合使用大、小写字母。例如:请将“/users/userId”更改为“/users/{id}”。请把POST“/deleteUser/userId”代替为DELETE“users/{id}”。
  • 始终在URL中使用版本控制,例如:我会将“/api/v1/”作为URL的必要组成部分。
  • 将“https”作为客户端连接的默认选项。
  • 请将负载验证组件作为代码处置的第一步。千万不可将其留到后期处理,甚至是留给异常捕获程序去处理。

4.处置升级

我曾经遇到过这样的一个案例:我们的某项服务一直使用着某个API来传递一些数据,但是某天它突然不工作了。在经过了多轮电子邮件和电话会议的讨论与研究后,我们最终才发现是因为该API的负载发生了变化--增加了一个必填字段。然而,我们在对该API的升级过程中,没有考虑到向后兼容这个问题!

为了避免此类错误,我们应当使用现有的CI(持续集成)流程,以尽早地检测出来。而作为一名API开发人员,您在更改目标API的时候,应该充分考虑现有的客户端。例如:在请求的正文中,那些新的字段,是应该使用默认值呢?还是应该定义一个诸如“/api/v2”之类的新版本端点?

5.测试

此处说所的测试,不只是功能性测试,也包括负载测试。您应该能够获悉目标服务器每分钟通常可以处理多少个API调用,以及在网络延迟增加时,响应时间会产生何种变化。如今,更多的企业会在全球范围内部署不同规模的数据中心,或是采用多区域的云端环境。例如:我们有必要了解到,您在美国西部托管的API服务器,是否能够给那些来自美国东部、欧洲、澳洲、甚至是亚洲的客户端实例请求,提供足够的带宽和连接数。

就我的个人经验而言,我更喜欢使用诸如:Postman或Apache JMeter之类的API测试工具,而不是从零开始编写工具与用例。它们不仅能够为我节省时间,还能够方便我轻松地check-in到git,并且导出各种模板。

总结

上述五点经验,便是我在实际项目中有关设计REST API的个人总结。希望它们能够为您的API开发,以及软件工程的其他方面,带来一些启发,让你少走一些弯路。

【原标题】5 Tips for Better REST API Design

 作者: Preetdeep Kumar

【51CTO译稿,合作站点转载请注明原文译者和出处为51CTO.com】

【编辑推荐】

  1. 数据中心的邻近度:如何更接近托管服务提供商?
  2. 是德科技旗下Ixia事业部助力服务提供商利用NFVi基准测试解决方案加速NFV部署
【责任编辑:武晓燕 TEL:(010)68476606】

点赞 0
分享:
大家都在看
猜你喜欢

订阅专栏+更多

大数据安全运维实战

大数据安全运维实战

CDH+Ambari
共20章 | 大数据陈浩

86人订阅学习

实操案例:Jenkins持续交付和持续部署

实操案例:Jenkins持续交付和持续部署

微服务架构下的自动化部署
共18章 | freshman411

174人订阅学习

思科交换网络安全指南

思科交换网络安全指南

安全才能无忧
共5章 | 思科小牛

107人订阅学习

订阅51CTO邮刊

点击这里查看样刊

订阅51CTO邮刊

51CTO服务号

51CTO官微