从草图绘制到实施交付：优秀 API 设计完整流程

[vocalman]

设计好的 API 是一项繁复的工作，但是优秀的设计是可以通过人为规划实现的，在本文中，我们将研究什么是好的设计以及如何在开发过程中实现它，还将介绍 API 设计的三个重要阶段：草图绘制，原型设计和交付实施，最后分享一些让工作更高效的工具。

优秀的 API 设计在迭代中发生

在开始设计 API 之前，先要了解其目的。从之前到你现在为什么需要构建 API 。了解目的能让你更好的遵循开发方向，不至于走偏。不过，定义目的只是第一步，真正的诀窍是在实施过程中做出良好的设计决策。

作为 API 设计人员，我们做出的每项决策都会对产品的成功产生影响。大的决策例如 API 传输协议，信息格式等。除此之外还有一些与插件，名称，接口顺序等的小决策。当你把它们放在一起时，所有这些决定都会构成一种使用模式。如果你都做出了最适合的决定，那么这种模式将帮助你设计你所需要的 API。

要想做出正确的设计决策，你需要先从错误的设计学习。事实上，在你摸索到正确之前，你可能需要犯很多次错误。这就是迭代的关键，没有人第一次就做对了，但是如果有足够的机会，你可以更接近预想。

照理说应该迭代我们的 API 设计，但在现实世界中很难做到这一点。因为在 API 发布后难以更改 API，更改正在使用的 API 既昂贵又有风险。解决此问题的一种方法是每次更改时避免大幅更改界面。这是一个很好的习惯，并且是良好的 API 设计的基本规则。但是，有时突破性变更是不可避免的。理想情况下，在更改变得有代价之前，应该解决所有可用性和设计问题。

迭代设计过程

每次迭代都让我们可以根据其用途来设计我们的项目内容。例如，开发人员是否能够使用我们构建的内容完成目标？这个界面真的可以实现吗？等等。我们应该能够通过设计和实现许多接口而不真正发布它们来实现最佳的 API 设计。所以查看和模拟测试每个界面将提供如何改进产品的实用经验。

但是在实践中，这种宏观迭代设计是不可能实现的。我们没有时间反复地设计和验证一个 API。更合理的方法是在设计过程中尽早执行迭代。这些早期的设计应该有足够的细节来产生改进机会，随着时间的推移，我们可以逐步提高细节（或保真度）的水平，直到最终达到我们想要的 API 设计。

这个渐进的过程在设计界很受欢迎，通常分为三个重要阶段：

1.草图的力量

草图是一种最普遍的设计行为。建筑师弗兰克盖里的草图非常有名，他的许多建筑项目都是以纸张上绘制的一系列草图开始的。他绘制了数百幅草图，每次都能接近理想的设计。

交互设计师 Bill Verplank 将草图描述为设计过程中必不可少的第一步。比尔·巴克斯顿（ Bill Buxton ）撰写了一本关于草图用户体验设计价值的完整书籍，提出了草图的关键特征以及重要性等。

在 API 设计过程的早期阶段结合草图使我们脑海中形成界面的概念模型。好的草图应该易于制作并且随时修正，如果花费太多时间来画图会得不偿失。

我们可以尝试不同类型的界面风格，并捕捉我们脑海中浮现的抽象概念。每一次的瞬间想法我们可以用草图的形式记录，方便我们审查和讨论它们。我们可以决定是否喜欢草图某个特定概念，然后在此基础上补充或者重新开始。

例如，我们可能会绘制一个与整个 API 相关的基本错误流或可应用于所有响应的响应消息格式。之后，在原型设计阶段，我们可以将这些想法应用到工作模型中。

2.原型设计

原型设计阶段是一个构建界面的更高保真度模型的过程，并测试我们在草图绘制过程中做出的一些假设。调用一个好的 API 原型，它应该处理实际请求消息并在需要时提供返回结果，甚至能够使用原型 API 创建一个简单的应用程序。

但是，构建原型应该比完全实现成本更低。降低成本的一种方法是模拟返回消息，而不是从后端系统提供实际结果。这就是 MOCK，是快速构建原型的好方法。

我们应该能够基于草图构建两个或三个不同的原型，在我们构建的过程中，我们甚至可以回到草图阶段，根据我们从原型设计阶段学到的知识来尝试新的方向。

原型还可以为您的团队提供了用户对设计的早期反馈并允许观察实际使用情况的机会。如果界面具有很高的保真度，您可以要求潜在用户在此基础上构建应用程序并观察他们过程中面临的问题。

精心设计的 API 不仅应该易于使用，而且还要具有可持续性，可靠性，高性能和长寿命。设计周期就像一个科学过程，原型阶段是你在做出改变之前测试任何假设的机会。

3.实施交付

开发者的工作是将原型界面变成可交付使用的。最终的原型和支持草图形成了界面应该是什么样的描述。它们反映了集体设计决策，以形成需要构建的规范。实际上，使用正式的接口描述语言从原型转换到实现阶段是很有用的。

例如，当您对原型 API 感到满意时，您可以选择在一些 API 管理工具如 EOLNKER 等中对其进行描述。

虽然实施交付是最后目标，但设计不应该停留在这个阶段。这是一个利用实际使用数据进一步测试您在整个设计过程中所做假设的机会。正如原型 API 允许我们观察使用情况一样，实现的 API 允许我们在真实情况下分析使用情况。

例如，您可能希望验证您所做的设计假设。应用程序开发人员是否真的使用您为他们创建的便利操作？您是否获得了预期的用户类型？新用户是否遇到界面特定部分的问题？

此分析可能会导致您再次启动草图绘制过程，以支持进一步改进的界面。

使用工具自动化流程

工具和技术可以从根本上改善设计过程。降低草图和原型创建成本的工具将使设计团队能够在更短的时间内生成更多设计，从而改进设计决策。

结合工具自动化是大多数设计过程的重要组成部分。在建筑设计领域，SHoP （总部设在纽约的建筑师联盟）通过创新，协作和基于工具的设计取得了成功。他们的工艺包括原型设计工具，使设计人员能够将所用材料的物理特性结合在一起。这种方法允许他们创建数千个设计迭代，每个迭代都包含可以轻松评估的实现细节。

API 设计领域中也有这种能优化的工具。实际上，全球范围内 API 服务领域中已经存在一些优秀的 Web API 设计工具。

现在，如 EOLINKER、RAML、Swagger，都提供了出色的编辑工具来支持他们的语言。其中 EOLINKER 作为国内较领先的 API 接口管理研发工具，正在以更全面的功能和简洁的页面超过如 RAML、Swagger 等国外传统单一服务产品。这些编辑器缩短了 API 的设计的创建时间，使得更容易在更短的时间内创建更多描述。点击查看 EOLINKER的 API 编辑器。

成功完成迭代过程

遵循本文中描述的迭代设计风格，你将为你的团队创建有效的 API。在流程开始时创建和评估许多低保真设计，以促进实验和构思。构建更高保真的原型和模拟实现来评估早期的设计理念。最后，为真实用户实施设计并收集数据以分析实际使用情况。

良好的 API 设计过程为您提供了生成最佳界面的机会。构建优秀 API 的秘诀不是专家指导或内部知识，相反，它是通过优秀的工具，语言和配置文件优化的迭代而成的，这会帮你完成越来越多优秀的 API。

参考资料：Ronnie Mitra，From Doodles to Delivery: An API Design Process 原文地址： https://www.infoq.com/articles/doodles-to-delivery/?useSponsorshipSuggestions=true