从涂鸦到发布——理解API的设计过程（转）

　　英文原文：From Doodles to Delivery: An API Design Process

　　要想设计出能够正常运行的Web API，对基于web的应用的基本理解是一个良好的基础。但若是你的目标是建立出优秀的API，那么仅凭这一点还远远不够。设计优秀的API是一个艰难的过程，若是它恰巧是你当前的工做任务，那么你极可能会感到手足无措。

　　不过，优秀的设计绝对是能够实现的。本文所描述的流程将帮助你得到成功，咱们将共同研究什么是优秀的设计，以及迭代式的流程如何帮助咱们实现这一目标。咱们还将叙述设计的三个重要阶段：草图设计、原型设计以及实现，同时还将介绍一些可以让你的工做变得更轻松的工具。

　　优秀的API设计来自于迭代过程

　　在开始设计API以前，咱们必须理解它的目的。在你手动设计以前，你应当了解为何要设计这个API，若是在这方面须要帮助，有许多现成的资料能够参考。不过，定义你的动机仅仅是第一步，真正的诀窍在于直到实现为止，始终保持进行正确的设计决策。

　　成功的API设计意味着要设计出一种接口，让它的使用方式符合它的目的。做为API设计者来讲，咱们所作的每一个决策都会影响到产品的成败。设计过程当中须要作出一些重大的决策，例如API所使用的传输协议、或它所支持的消息格式。但除此以外，还有许多相关的次要决定，例如接口的控制、名称、关联以及次序。而当你将全部的决策集中在一块儿时，它们将带动API的使用模式。若是你可以作到每一个决定都是正确的，那么这种模式将对API产生完美的支持与促进做用。

　　若是你要作出一个正确的设计决策，极可能会先作出一个错误的决策，并从中吸收经验教训。实际上，你极可能会在屡次犯错以后才可以接近正确的决策。这也正是迭代的关键所在，由于没有人可以作到一次成功，但只要有足够的机会，你就可以作到接近完美。

　　经过迭代方式进行API设计，这一点提及来容易，但在实际应用中作到这一点并不简单。咱们所面临的一个常见的挑战在于，在某个API发布以后再进行变动是很是困难的。事实上，对一个使用中的API进行变动的代价很大，而且伴随着很大的风险。或者借用Joshua Bloch的说法：“公开的API就像钻石，它是永恒不变的。”

　　处理这一问题的一种方式是在每次变动时不要破坏现有的接口，这是一种好习惯，也是优秀API设计的一个主要原则。但有些时候，破坏性的变动是不可避免的，而基本层面的设计变动尤为具备侵略性。

　　换种思路，咱们应当在接口发布以前就作好这些变动。在理想的状况下，在变动的代价变得高昂以前，就应该消除易用性与设计方面的问题。当时，只有在首次发布以前作到尽早开始迭代，并保持频繁的迭代，才可以找到并修复这些问题。

　　迭代式的设计过程

　　在每一次迭代中，咱们都获得了一次对设计候选按其使用状况进行评估的机会。举例来讲，开发者是否可以经过使用咱们建立的产品实现他的工做目标？这个接口真的可以实现吗？若是咱们要求他人使用这个API，他们又会有什么样的感觉？

　　经过设计与实现多个接口而不发布它们，应该可以实现最佳的API设计。经过对每一个接口进行审查与测试，咱们将对于如何改进最终产品具备良好的洞察力。

　　可是在实践中，这种壮观的迭代式设计是不可能实现的。没有几我的能有足够的时间、金钱或耐心去不断地设计与实现一个个能够运行的API。对于任何具备必定复杂度的接口来讲，这种方式的迭代式设计会占用你过多的时间。

　　一个更合理的方式是在设计过程的早期就进行迭代，这些早期的设计应当具备足够的细节，可展示改进的最佳时机，但又无需过分设计而致使实现的困难。随着时间的推移，咱们能够逐步地增长细节度（或保真度），并最终获得一个完整的实现。

　　这种逐步推动的设计过程在设计界已经很是流行了，它一般被分解为三个重要的阶段：

1. 草图设计
2. 原型设计
3. 实现

　　草图设计的强大做用

　　草图设计是设计方面的一种广泛行为。著名建筑师Frank Gehry的草图可谓天下闻名，以致于诞生了一部专门描述这些草图的电影。他的许多建筑项目都是从在一叠纸上所画的一系列草图开始的。Gehry总会画上几百张这样的草图，每一次都向良好的设计更靠近一步。

　　交互设计师Bill Verplank将草图设计描述为设计过程当中必不可少的第一步。Bill Buxton还专门写了一整本书，用以介绍草图设计方法对用户体验设计的价值，并认为它的关键特征在于它的可弃性、并且在全部探索方式中是成本最低的一种。

　　将草图设计过程包含在API设计过程的早期阶段，让咱们有机会体验接口的概念模型。这不只是一次定义咱们脑中已有的想法的好机会，也让咱们有机会探索新的道路，而且提出“若是……会怎么样？”这样的问题，并逐步走向真正的创新。

　　优秀的草图应当是易于建立、而且能够任意丢弃的。若是建立这些草图花费了许多时间、或是难度过高，那么你就难以丢弃它们。这种可弃性很是重要，它让咱们有机会承受住风险。

　　咱们能够经过草图设计尝试不一样类型的接口风格，并捉住那些在咱们脑海中时而闪现的抽象概念。一旦这些思想具体化，咱们就可以对它们进行审查及讨论。在过程当中决定咱们喜欢或是不喜欢某个特定的概念，而后在消化了这些知识后再次启动这一过程，并绘制新的草图。

　　对于设计团队以外的用户来讲，他们不多会对草图进行评估。不只是由于过早地对假设进行验证是没有价值的，而且在实际的项目中可以进行的用户测试次数是有限的。经过真实的用户对每种草图都进行测试的设想代价太高，而这种方式的收获是很是有限的。

　　使用档案进行草图设计

　　在进行API的草图设计时，使用档案（profile）或元语言（meta language）是一种很是实用的方式。档案提供了一系列的概念，可用于草图的设计。一个优秀的档案能够类比为框与线，经过它建立系统图的多种草图。这些元素是设计师与评估者都可以理解的内容，它让快速地开发草图变得更简单。

　　实际上，着手进行API草图设计过程有一种好方法，就是定义接口中最明显的单词列表。有哪些单词是用户必须知道的？哪些单词可以最好地表达你的目标受众的目的与任务？经过回答这些问题，并建立一份接口的词汇表，将有助于你造成对该接口的一种早期草图。

　　档案的美妙之处在于，它为咱们提供了一种正规化的方式以共享及重用这种类型的信息。举例来讲，咱们在开始设计时可能会从某个XML结构文档中提取出单词、从schema.org获取一份词汇表、或者从某个ALPS或RDF文档获取信息，这取决于咱们的需求。

　　设计阶段的目标并不是建立一份全面的词汇表，偏偏相反，早期的词汇表只是一个起点，咱们能够从这一点开始绘制出其它类型的细节。咱们可能会发现一个由20个左右的单词组成的列表就可以捕获接口的本质，这个列表就能够做为咱们的起点。

　　这份词汇表为咱们提供了一个基础，咱们能够从它出发为API中的资源与关联设计草图，内容能够包括URI、资源名称、资源间的关联、连接文本以及其它结构化以及导航元素。请再次注意，没有必要画出草图的全部细节，咱们的目标是表达出API里最重要的部分。

　　最重要的一点在于，最初的草图无需过于深刻。比方说，请尽可能避免在这一阶段就深刻到错误流的建模，或响应消息元素的设计。这些部分能够稍后再加入，或者能够为它们进行专门的草图设计。

　　一份单独的草图无需反映出整个接口，实际上，为某些细节部分专门设计草图的方式可能更实用。举例来讲，咱们能够设计一个基本错误流的草图，它与整个API都具备相关性，或是设计一种响应消息格式的草图，这种格式能够应用到全部响应中。以后，在原型设计阶段，咱们能够将这些思想应用到某个工做模型中。

　　原型设计

　　在原型设计阶段，咱们将有机会为接口设计一个具备更高保真度的模型，而且对草图设计阶段产生的一些假设进行验证。一个优秀的API原型应当是能够调用的，它应当可以处理真实的请求消息，并在必要时提供响应。开发者甚至应该可以经过使用这个原型API，建立出一个简单的应用。

　　不过，建立原型的成本应当低于一个完整的实现。有一种方法能够保持较低的成本，即模拟响应的消息，而不是由后台系统输出真实的响应消息。这种方式有时也称为接口的虚构（mocking），它是一种创建快速原型的好方法。

　　不管使用哪一种方法创建原型，要点在于为投入找到一个合适的范围，可以支持后续的迭代。咱们应当可以基于草图建立出两至三个不一样的原形，并在过程当中持续地学习。根据咱们在原型设计阶段所学的内容，咱们甚至可能会返回草图设计阶段，并尝试全新的方向。

　　经过原型，你的团队将有机会得到对于设计的早期用户反馈，而且可以对真实的使用状况进行观察。若是该接口的保真度已经达到了必定程度，你就可让潜在的用户建立应用，而且对他们在实现阶段所面临的挑战进行观察。

　　负责实现的成员也应当加入原形评估过程当中。一个通过良好设计的API不只应当易于使用，同时仍是可持续的、可靠的、高性能的、而且是历时长久的。虽然接口自己不该暴露数据模型的内部细节与服务器的架构，但负责实现者为告诉设计团队所作的决定提供一些参考建议，例如运行环境的限制，以及实现的成本。

　　设计周期比如一个科学工艺流程，而你应当抓住原型阶段的此次机会，在提出变动还为时未晚时对所作的假设进行验证。

　　实现

　　实现者的任务是将一个原型化的接口转变成一种能够放心地进行实际应用的产品。交付一个安全的、可靠的、以及可伸缩的实现是一个很大的挑战，这一过程自己也须要经历一种专门的设计流程。

　　最后的原型以及支持性的草图描述了接口应该表现出的样子，它们反映出了全部的设计决策，并造成了一份规格，说明了具体须要建立什么样的产品。实际上，可使用一种正式的接口描述语言（或称IDL），从原型阶段天然地过渡到实现阶段。

　　举例来讲，若是你对原型API感到满意，就能够选择以一种API Blueprint文档（或Swagger、RAML、WADL，又或者是其它任何一种最适合你工做环境的格式）对其进行描述。

　　虽然这一阶段的目标是实现，但也不该停下设计的脚步。这一阶段是一个良机，让你经过真实的使用数据对整个设计过程当中所作的假设进行进一步的验证。就像原型化的API容许咱们观察使用状况同样，实现后的API容许咱们在一个宏观层面对使用状况进行分析。

　　打个比方，你或许想对你以前所作的设计假设进行验证。应用程序的开发者是否真的在使用你为他们所建立的便利的操做？你是否吸引到你所指望的用户类型？新的用户是否在使用接口中的某些部分时遇到了麻烦？

　　通过分析，你可能会从新开始一次草图设计过程，以准备进一步改进接口。

　　经过工具实现过程的自动化

　　工具与技术的使用会极大地改进整个设计过程。那些可以下降草图与原型建立成本的工具可以让设计团队在更短的时间内建立更多的细节，使设计的决策获得改进。

　　对于多数设计过程来讲，工具与自动化的引入是一个重要的部分。在建筑设计的世界中，SHoP（一个位于纽约的建筑师事务所）就经过创新、合做与基于工具的设计得到了成功。他们的流程中就引入了原型工具，让设计师可以体现出所用材料的物理特性。这种方法让他们得以建立数以千计的设计迭代，在每次迭代中都可以体现出易于评估的实现细节。

　　在API设计的世界中，这种基于工具的优化有很好的表现机会。实际上，在服务描述领域中，已经出现了一些卓越的Web API设计工具。

　　接口描述语言也可以提供支持性的工具，以简化编写描述的任务，这一点如今已经很常见了。这些编辑器工具可以缩短基于IDL的设计的建立时间，所以在更短的时间内建立更多的描述也变得更容易了。Swagger、RAML与Blueprint都提供了优秀的编辑工具以支持各自的语言。即便像WADL这样仅做为规范发布的IDL，也可以从SoapUI这样的工具中受益。

　　Apiary为Blueprint语言所提供的编辑器有很强的竞争力，由于它提供了一套完整的工做流工具以支持设计过程。只要以Blueprint编写一个简单的API描述，设计师就可以对文档进行评估、调用原型，甚至对调用过程进行分析。

　　不过，这些现有的工具中的大部分都只限于其所支持的描述语言。设计者必须理解IDL的语法，而且用这种语言设计界面。虽然这种设计风格可以吸引熟悉编程语言的使用者，但也会限制在早期的草图设计阶段颇有价值的抽象与实验性的思考方式。

　　因为IDL及其对应工具的这些特征，它们很适用于原型设计过程，但对于草图设计的早期实验性活动来讲实用性不高。

　　使用可视化工具进行草图设计

　　人们对于使用可视化工具帮助他们进行API设计的兴趣正在不断升温。这些工具并不是直接支持编辑IDL的行为，而是让设计者可以随意摆弄接口的一个可视化展示。

　　可视的建模工具提供了一种接口描述语言，这种语言多数是关于绘画的，或是基于图形的。虽然这个视角限制了接口展示的准确度，但它也让设计者可以在一个较高层次看到这个接口的全貌。这一点带来了进行改进的机会，而这种机会在手写的形式中每每并不明显。

　　易于使用的可视化编辑器也是进行自动化草图设计的良好选择，它综合了低保真度、抽象的展示以及可弃性等特征，这正是咱们所需的。

　　我参与开发了一个名为Rápido!的可视化建模工具，用于辅助API的草图设计。Rápido将用户限制在一个低保真度的细节中，这一点并不是它的反作用，而是自己就是如此设计的。用户可使用它进行档案、导航元素以及响应数据的建模，但不能用于设计逻辑流程或动态的响应。

　　当设计者开始建立一个新的Rápido项目时，他们须要为API设计一个词汇表。在获得一个初始的单词列表（或者从外部导入一个ALPS词汇表）以后，设计师就能够在一个超媒体画布中开始为API设计概念模型、建立资源、尝试URI名称甚至是连接的状态。

　　最终，设计者能够为草图中的每一个资源或状态实现静态的响应消息，以增长保真度。最后，当草图设计阶段结束后，能够将整个设计导出成IDL格式，准备在原型阶段导入高保真度的工具。

　　Rápido的目标是在Web API设计的领域中提供一种快速绘制的“鸡尾酒餐巾”式的草图的体验。若是你选择了适当的保真度，而且没有施加过于强烈的限制，那么它就可以成为API设计工具链中的重要一环。

　　在迭代过程当中取得成功

　　若是你按照本文中所描述的方式进行迭代式风格的设计，那么你将为团队带来一个设计高效API的良机。在过程的一开始建立多个低保真度的设计并进行评估，以培育实验能力与构思能力。而后建立高保真度的原型以及虚拟的实现，以评估早期的设计思想。最后，为真实用户实现整个设计，并获取数据以分析实际应用中的使用状况。

　　迭代式设计过程的特定细节取决于你的环境与项目，须要多少细节、多少次迭代、以及须要哪些评估技术，这些问题将留给设计者进行回答。但做为一种通用的经验法则，随着你的设计过程的推移，迭代的数量应当逐步减小，而在评估方面须要投入更多的精力。

　　优秀的API设计过程为你提供了一个建立最佳的接口的机会。但建立优秀API的秘密并不在于专家的指导或什么神秘的知识，而是一种经过优秀的工具、语言以及档案所优化的迭代流程的应用而实现的。使用这个公式所交付的API定能帮助你的组织得到成功。

http://kb.cnblogs.com/page/527814/