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

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