设计标准的RESTful API

设计标准的API是一项很困难的任务，包含有很多主观指标。即使是一家完全接受RESTful API设计原则并对其问题空间有完整看法的小型初创公司，最终也可能会出现命名不一致、接口模糊和语义不规范的情况。当一个拥有许多不同开发团队的大型组织以一种特殊的方式面对这些相同的挑战时，其影响是复杂的，并常常导致API产生隔阂，使它们难以从中脱颖而出。在本文中，我将讨论三种可帮助您的企业API避免这些隔阂的实践。

正确理解语义

最重要的是要正确的语义。正确的语义指的是API端点和查询字符串参数的命名、传递的数据结构的布局、HTTP报头的使用以及有关返回HTTP状态代码的约定。不同的设计师经常从完全不同的角度解释RESTful接口的基本原理，并且解释最终变得非常主观。在端点的命名以及参数和数据结构的使用中最为明显。

API端点名称是用户遇到的API中最明显的方面，与任何其他特性相比，更能向用户传达有关RESTful API设计的信息。无论端点是为资源（客户），流程（清单）还是介质（移动设备）命名的，如果在问题空间和业务中使用一致地约定，API将会更加易于理解。在大型企业中，要达到这种一致性水平的唯一方法是要制定严格的规定，并在所有开发团队中应用这些规定。

除了API端点命名之外，还存在命名参数和数据结构的问题。不同的接口将具有不同的数据需求，但这里也应该采用和使用样式约定。如果使用“ OneAPIDoesThis”和“another_does_this”，那么这些API放在一起就不那么容易理解了。同样的情况适用于通用参数或通用数据结构。如果两个端点都使用了Access Token，那么它们使用相同的名称通常会更好。

发现和文档

即使拥有良好的RESTful API设计和一致的应用约定，但是如果用户不能轻松了解这些设计功能并探索使用不同端点的方式，那么它们对用户几乎没有好处。在设计新的API或记录API可以使用API管理工具，工具可以帮助我们定义端点作为模型类型返回的数据结构，记录字段，无论它们是必需的还是可选的，以及值范围和约束。这节省了大量的工作，并且非常保证您的代码在有效的输入上运行。

访问和可测试性

用户在使用新API时遇到的早期障碍之一就是弄清楚它的工作原理。无论端点的名称，或者文档的可用性如何，大多数开发人员都需要在新客户端的早期开发过程中测试API。我最喜欢的API测试工具是名为Eolinker：www.eolinker.com。Eolinker允许定义端点的命名集合，以及执行每个端点所需的URL，请求参数，报头和主体数据。定义后，只需单击即可执行端点，并报告调用的性能，以及访问有关响应的详细信息。另外Eolinker还可以导入Swagger规范并为您生成API。

当然，在开发新的API时，还有许多其他重要的设计和实现考虑。其中最有影响的是你如何决定对它进行版本控制。目前而言，我相信遵循以上概述的做法可以帮助您创建整个业务中保持一致的API，这些API可由用户发现并按需进行文档化，并且可由客户端开发人员轻松测试的API。总而言之，这是三种有助于避免企业API管理混乱的方法。