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

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

[[333102]]

【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】

 

责任编辑:武晓燕 来源: 51CTO
相关推荐

2016-12-30 14:47:21

设计RESTfulAPI

2022-02-10 23:38:23

API架构设计

2023-09-21 11:20:46

2023-10-30 18:59:38

REST API开发

2022-06-21 09:27:01

PythonFlaskREST API

2020-04-22 09:00:00

REST API参数化前端

2018-04-20 09:00:47

UI设计应用程序易用性

2011-12-12 15:51:20

RESTSOAP

2012-06-27 09:47:05

ibmdw

2024-01-23 09:08:47

软件架构REST

2019-11-13 11:52:46

区块链API比特币

2023-08-14 09:00:00

APIgRPCREST

2011-10-27 16:24:48

API

2022-08-05 14:46:28

区块链Web 3.0NFT

2023-02-03 17:29:46

2010-01-08 12:03:42

ibmdwREST

2023-05-11 12:40:00

Spring控制器HTTP

2022-05-06 09:52:17

REST接口API

2019-08-13 09:00:24

REST API身份认证密钥

2022-07-06 14:51:07

人工智能技术研究
点赞
收藏

51CTO技术栈公众号