成功的API设计需要对细节的大量关注。遵循以下三个步骤来做好RESTful API设计。

设计好的API是一项困难的任务，存在很多主观指标。哪怕是完全拥抱RESTfulAPI设计并对其问题域拥有完整视图的小型初创企业最终也会出现命名不一致、界面模糊以及无记录语义等问题。当一家有着许多不同开发团队的大型组织以特定方式遭遇这些相同挑战时，其影响是参差不齐的，往往导致API陷入到一个个烟囱当中，让它们很难显现。在本文当中，我将讨论三种实践，这三种实践可以帮助你的企业API避免这些陷阱。

语义要对

要搞清楚的最重要事情是语义。这个词使用起来非常宽松，但是在这里我指的是API端点以及查询字符串参数的命名，传递的数据结构的布局，HTTP头的使用，以及围绕着返回HTTP状态码的惯例。不同的设计师往往对RESTful（表属性状态转移）接口的基本原则解释有着颇为不同的观点，而解释的质量最终是非常主观的。这一点在端点的命名以及参数和数据结构的使用上实在是太正确了。

API端点名是API对消费者来说最显而易见的东西，比任何其他特性向消费者传达的东西都要多。无论一个端点是否被命名为资源（客户）、进程（存货）或者甚至是媒介（移动），如果那些约定在整个问题域和业务域都一致应用的话API就会更加容易理解。对于大型企业来说，实现这种一致性程度的唯一方式是要有协商清楚的一致约定并且定期应用到各个开发团队上。达到那个理想水平需要在管理上不断实践，而不仅仅是设计好就行了。

除了API端点命名以外，你还有参数命名以及数据结构命名的问题。不同的接口会有不同的数据需求，但是风格约定也应该得到采纳和使用。如果“OneAPIDoesThis（一个API做这个）”，“另一个做那个”，那么API凑在一起就没那么容易理解。这一点同样适用于共同参数或者共同数据结构。如果端点要用一个访问令牌，通常如果他们给它取同样地名字的话会更好。要想就API命名约定得到一些好的提示以及知道如何去应用这些提示，可以看看Netflix或者Twitter这些主要玩家的指南。

发现和存档

即便你有了好的RESTful API设计，且应用了一致的约定，如果他们不能很容易了解到这些设计特性并且探索不同端点的使用方式的话，对于API的消费者来说基本上也没有什么好处的。幸运的是，我们有Swagger，这是我最喜欢的API设计与测试工具之一，也是我一旦经过了最初的概念化阶段开始设计新API时求助的第一个工具。

Swagger在本质上属于用结构化的方式描述RESTful API的一个规范，采用的是要么JSON要么YAML这样的标记语言。围绕着这一规范是一组编辑标记并生成免费东西的工具：存根（stubs）、端点测试，以及好的TML文档。我发现Swagger有两个东西特别。一是由于它是标记性的，你的API规范可以成为特殊“自文档”端点（通常是命名的Swagger）的返回类型。消费者可以用这个端点迅速访问你API的结构化规范。

我喜欢Swagger的第二个点是模型验证。作为给API编写文档过程的有份你要定义端点作为模型类型返回的数据结构。你可以对字段（无论是必选还是可选）进行文档记录，同时还可以对值域和约束进行记录。完成这些以后，你可以用像bravado-core这样的库在运行时验证输入数据是否符合模型规范，并给在验证失败时返回详细的错误信息。这可以节省一大堆的工作，并且给你很大的信心，相信自己的代码是基于合法输入运作的。

访问与可测试性

消费者在跟新API打交道是遭遇的早期壁垒之一是弄清楚它是如何工作的。无论端点的命名有多好，也无论文档写得有多好如何容易获得，作为新客户早期开发过程的一部分大多数开发者都需要测试API。我喜欢的API测试工具无疑是一个叫做Postman 的Chrome浏览器插件。Postman可以让你定义命名的端点集合，以及URL、查询串参数、需要执行的头和体数据。一旦定义好了，一次点击就可以执行端点，并且回报调用的性能以及给出对响应详细信息的访问。

一旦集合定义好，就可以分发给消费者以各种方式自行使用：一是可以上传给Postman服务器，这个过程可以在返回URL客户端后再通过下来访问。这个集合还可以导出为JSON充当你自己服务器上的端点，如果API不开放的话可以优选这种方式。我往往出于这一目的来使用端点和Postman。这是Swagger有所帮助的另一个领域，因为Postman可以导入Swagger规范并且替你生成一个端点集合。再也没有比这更容易的了。

当然，在开发新API时，还有很多其他重要的设计和实现考虑。最重要的影响之一是如何决定对它进行版本控制，这个话题值得另起一篇文章进行讨论了。目前为止，我认为按照上述概括的实践做法已经可以帮助你创建跨整个企业一致性、消费者可发现、按需自文档以及客户端开发者容易测试的API了。总之可以有三种方式帮助避开企业API管理的混乱。