什么是 API 设计？

API 设计是指开发应用程序编程接口（API）的过程，该接口可公开数据和应用程序功能以供开发人员和用户使用。API 对于现代企业而言至关重要，可以为其运营和产品以及合作伙伴战略等各方面增加新的功能。大多数企业对于是否应该开发 API 程序已不再存有疑虑，而是想要知道具体的实践方法。

有效的 API 程序必须建立在企业的总体战略基础之上，并助力其实现目标。当您能够明确回答以下 3 个问题时，您便可确定自己将会制定出有效的战略：

1. 我们为何需要实施 API？
2. 我们希望通过这些 API 实现哪些具体成果？
3. 我们如何计划执行 API 程序来实现这一目标？

原因

人们经常以不同的方式误解这个问题。首先，要思考 API 效果的价值，而不是关注 API 本身的价值。请记住，企业的核心业务才是有价值的，不一定是 API。当 API 成为提供对企业所提供的现有价值的新访问类型的渠道时，它就很有价值。

另一个常见错误是认为 API 本身很有价值，用户必须准备为其付费。仅当 API 本身是产品时才是这样。在大多数模型中，情况并非如此。API 通常会推动其他一些指标——销售、会员推荐、品牌知名度等。API 对用户的价值是 API 调用（服务请求和响应）的结果，而不是调用本身。

根据 Cutter Consortium 和 Wipro 对 152 家企业进行的调查，建立 API 计划的最常见业务驱动因素是开发新的合作伙伴关系，增加收入，利用新的商业模式，缩短产品上市时间，以及开发新的分销渠道。最重要的技术驱动因素是改进应用集成，改进移动集成，并支持与更多设备的连接。API 所能带来的益处必须足够诱人，以便促使企业毫不犹豫地选择进行 API 投资。

内容

第二个问题是"我们希望通过这些 API 实现哪些具体成果？" 换言之，"API 的实际用途是什么及其对更广泛的业务战略有何影响？"

企业的内部视图和外部视图概念都有助于定义 API 的内容。内部视图是指企业拥有的具体且有价值的资产。提供的服务和资源越是有价值和独特，就越适合用于 API 程序。

拥有特有数据的企业可以允许通过 API 来访问这些数据，以便充分利用这一资源。特有的内容、数据和服务会让 API 访问权限变得异常宝贵。

在决定 API 应该为企业做什么时，需要检查
内部和外部视图。而有关内容的决定通常是这 2 种视图的结合。

具体而言，虽然原因不太可能经常改变，但根据市场、技术考虑因素或经济条件等外部因素的不同，内容可能会有很大差异。关于资产价值的内部指示可能会发生变化，这也可能会影响使用 API 应该实现的目标。

方式

最后一个问题，"我们如何设计 API 程序来实现我们的需求？"全在于实现和执行。

团队必须自问：

• 使用什么技术来构建 API？
• 如何设计 API？
• 如何维护 API？
• 如何在企业内部推广 API 或外销 API？
• 哪些资源可用？
• 谁应该加入团队?
• 我们如何根据已设定的业务目标获得成功？

API 团队与"产品"团队的关系最为密切——无论您的客户是内部客户还是外部客户，您都要负责构建、部署、运维和优化其他人所依赖的基础架构。

就像产品团队一样，API 团队也可以非常多样化，但通常应该包括以产品为中心的人员（战略和目标负责人）、以设计为中心的团队成员（确保最佳 API 设计实践）、能将 API 技术落实到位的工程师，以及将要运行 API 的操作团队成员。

随着时间的推移，您可能还需要其他人员加入，包括支持和社区团队成员、API 传播者、安全代表等。

John Musser 在 2012 年的 O’Reilly 开源项目大会上重点谈论了出色 API 的 5 个"关键点"：

1. 提供有价值的服务
2. 创建计划和业务模式
3. 使其简单、灵活、易于采用
4. 应该对其进行管理和衡量
5. 提供出色的开发人员支持

在思考使用 API 程序的原因时，第一个关键点"提供有价值的服务"尤其重要。价值主张是 API 成功的主要推动因素。如果 API 具有错误的价值主张（或根本没有），则很难或不可能找到用户。

几乎任何拥有现有产品（数字或物理）的公司都可以
通过 API 产生价值，前提是该 API 链接到现有产品并对其加以改进。只要 API 的构造方式能够为开发人员提供有意义的用例，它就能带来价值。

查找和描述 API 的价值是一个迭代过程。第一步是描述用户将尝试完成的工作。例如：

• 在紧急情况下自动向团队成员发送紧急通信
• 备份关键文件以确保它们永不丢失
• 对数据进行采样以检测特定事件

接下来，确定会在尝试完成工作之前、期间或之后影响用户的具体难题：

• 通过多次尝试、检测故障、担心发送多个消息而不只是一个消息，并根据用户的位置与不同的消息传送系统集成，确保发送可靠性
• 确保安全传送文件，同时还要最大限度地减少传输带宽
• 处理大量数据并尝试实时关联它

第三步是总结用户可能获得的潜在收益：

• 发送其他类型的通知，这些通知创建机会而非威胁警告
• 如果可靠性能达到您的要求，则可去除其他存储设备
• 根据事件自动触发操作

在审视这些痛点时，请多多思考，并列出支持、文档或开发人员门户等内容，以及用户可以使用的所有内容。接下来，概述您打算如何消除或减少在尝试完成作业之前、期间或之后可能令 API 用户烦恼的一些事情，或者阻止他们这样做的问题。然后描述您打算如何为 API 用户创造任何形式的收益。

通过参与此过程，我们上面的 3 个示例可能会导致：

• 多通道消息传递 API，只需一次调用即可传递消息，并且能够自动重试直至保证送达（例如，Twilio、PagerDuty）。
• 具有优化调用的存储同步 API，以有效地检查是否应同步新版本（例如，Bitcasa、Box）。
• 将多个数据源聚合为一个可配置流的 API，可对其进行过滤、采样和轻松操作（例如，GNIP、DataSift）。

最后，进行一个有用的澄清练习，即组合几个语句，使 API 和用户配置文件之间的适配清晰。如果您发现难以识别这样的适配语句，则需要重新考虑 API 模型。也许有 API 功能需要添加、修改、改进或消除。也可能是您的 API 确实提供了很大的价值，但您正在尝试解决用户的错误类型。

然后，当您将适配语句压缩为一个总体语句时，它就成为您 API 的价值主张。对于上面的消息传递 API，这可能是这样的：

我们的消息传递 API 为企业开发人员提供可靠、有保证、无延迟的文本消息传递功能，用于高度关键的业务应用。软件开发工具包（SDK）也支持此 API，涵盖最常用的编程语言，以实现快速集成。

有时，您可能会想"这好像太复杂了。我们只不过是要创建一个内部 API。" 但是，即使在内部用例中，对于价值的关注也至关重要。定义不明确的价值主张将导致难以将 API 推销给其他团队。定义明确的价值主张不但有助于 API 程序的采纳推广，还能使其成为业务的主要促进因素。

为帮助定义您自己的 API 程序的价值，请考虑以下 5 个问题：

1. 谁是用户？这个问题应根据他们与您的关系（他们是现有客户、合作伙伴还是外部开发人员）、他们的角色（他们是数据科学家、移动开发人员还是运维人员）以及他们的要求或偏好来回答。
2. 我们要解决哪些用户痛点和/或为用户创造什么收益？这个问题应根据与客户业务的关系、价值主张中确定的难题和收益、是否满足关键需求（这是痛点还是收入机会），以及正在为用户改进的衡量标准（速度、收入、成本节省、创新能力）来回答。
3. 您的 API 支持哪些用例？借助价值主张，识别对您所在企业和用户最有效的用户难题解决方案或 API 商机。计划 API 以解决这些用例。
4. 如何随着时间的推移扩大用户的价值？ 计划您的价值主张，并考虑未来的变化。与内部或外部变化相关的即将到来的重要里程碑是什么？
5. 将在内部为您的企业创造什么价值？考虑内部收益以及 API 如何在业务中具有价值。

在设计基于 API 的程序时，务必要能阐明 API 的价值。但是，API 也会产生成本，这一考虑应该通过价值来平衡。虽然价值可能无法以货币形式衡量，但必须是真实的。例如：

• 企业的现有核心业务是什么？
• 如何使用 API 来加速或扩充企业的业务发展？

在某些情况下，API 可以在企业的现有业务模式之外产生全新的商机。但即使在这种情况下，API 通常也会利用现有资产或专业知识以新的方式来创造商机。

总之，以下 3 点就是为什么确定正确的业务模型对于设计有效的 API 程序而言至关重要的原因：

1. 确定正确的业务模型可以突显 API 对于企业的价值，这推动了关于 API 程序长期承诺的决策。如果没有这种承诺，很少有资源可用于完成建立和运行有效 API 程序所需执行的任务。
2. 确定正确的业务模型有助于定义产品的功能，这是满足第三方并推动业务发展所需的。
3. 确定正确的业务模型可确保考虑企业内的角色和职责，以及谁保留 API 生成的价值的哪些部分。这也意味着定义使用 API 能为 API 用户带来的收益以及如何与 API 提供商的收益进行平衡。

好的 API 设计有一些核心原则，这些核心原则在实施上可能有所不同。就好比：每辆车都有方向盘、刹车踏板和加速器。您可能会发现各款车型的危险警告灯、行李箱释放装置或收音机略有不同，但很少有经验丰富的司机不知道如何驾驶出租车。

这种"驾驶就绪"设计水平正是出色的 API 团队所追求的——经验丰富的从业者很少或不需要解释就能开始使用的 API。

简单性

API 设计的简单性取决于环境。特定设计对于一个用例可能很简单，但对另一个用例来说非常复杂，因此必须平衡 API 方法的粒度。在多个层面上考虑简单性可能很有帮助，包括：

• 数据格式。支持 XML、JSON、专有格式或组合。
• 方法结构。方法可以非常通用、返回一组广泛的数据，或者非常具体以允许有针对性的请求。方法通常还以特定顺序调用以实现某些用例。
• 数据模型。底层数据模型可能与通过 API 实际显示的内容非常相似，也可能大不相同。这会影响可用性和可维护性。
• 身份验证。不同的身份验证机制具有不同的优缺点。最合适的机制取决于环境。
• 使用策略。开发人员的权利和配额应易于理解和使用。

简化 API 可能会与使其变得灵活相冲突。仅考虑简单性而创建的 API 存在过度定制的风险，仅为非常具体的用例提供服务，对于其他用例而言可能不够灵活。

要建立灵活性，首先要找出潜在的操作空间基于什么，包括底层系统和数据模型，以及定义这些操作的哪些子集是可行且有价值的。为了在简单性和灵活性之间找到适当的平衡：

• 尝试公开原子操作。通过组合原子操作，可以覆盖整个空间。
• 确定最常见和最有价值的用例。设计第二层元操作，该操作结合多个原子操作来为这些用例提供服务。

按理说，超媒体即应用状态引擎（HATEOAS）的概念可以进一步提高灵活性，因为它允许在 API 和客户端操作中更改运行时。HATEOAS 通过简化版本控制和文档编制确实提高了灵活性，但是，在 API 设计中，必须考虑许多问题。

为了全面思考您的 API 设计，请考虑以下 5 个问题：

1. 我们是否设计了 API 来支持我们的用例？确定主要用例之后的下一步是设计 API 以使其支持这些用例。灵活性很重要，以免排除可能不那么频繁但仍应受支持的任何用例，以允许创新。
2. 我们是否要为此使用 RESTful？RESTful API 目前很流行。但是，不应该仅仅为了这个目的而追随这一趋势。有些用例非常适合它，但其他用例优选其他架构风格，比如 GraphQL。
3. 我们是否在未考虑用例的情况下公开了自己的数据模型？API 应得到实际数据模型中抽象出来的层的支持。一般说来，没有直接进入数据库的 API — 尽管可能存在需要的情况。
4. 哪些地理区域最重要，我们是否相应地规划了数据中心？API 设计还必须涵盖延迟和可用性等非功能性元素。确保选择地理位置接近您拥有大多数用户的数据中心。
5. 我们是否正在将 API 设计与其他产品同步？如果 API 不是您公司的唯一产品，请确保 API 设计与其他产品的设计协调一致。您可能决定将 API 设计与其他产品完全分离。即使在这种情况下，也需要明确将 API 设计与其他产品完全分离的具体计划，并在企业内部和外部进行相应的沟通。

改进 API 设计以便于采用的关键指标是"Time to first hello world"（TTFHW，即"首次问世时间"）。换言之就是，开发人员需要多长时间才能使用您的 API 创造出最小可行产品？这是让自己为开发人员着想的好方法，开发人员想测试您的 API 来了解如何使某些工作变得有效。

当您定义 TTFHW 指标的开始和结束时，我们建议尽可能多地涵盖开发人员参与流程。然后优化它，使其尽可能快捷方便。

能够快速完成整个过程还可以使开发人员确信 API 组织得很好，并且事情可能正常工作。将"成功时刻"延迟得太久可能有失去开发人员的风险。

除了 TTFHW，我们还推荐一个指标："Time to first profitable app"（TTFPA，即"首次盈利应用时间"）。这更为棘手，因为"盈利"是一个定义问题，具体取决于您的 API 和业务战略。考虑到这一点很有帮助，因为它会迫使您将与 API 操作相关的方面视为 API 程序的一部分。

开发人员体验的两个基本原则是：

1. 设计一种产品或服务，为开发人员提供明确的价值并应对显而易见的难题或商机。这可以是货币价值或某些其他价值，例如提高覆盖率的方式、品牌知名度、客户群、间接销售、开发人员声誉或使用有效先进技术的纯粹乐趣。
2. 产品需要易于访问。这可以包括具有轻量级注册机制（或者根本没有）、测试功能访问、优秀文档以及大量免费和整洁的源代码。

我们建议大多数 API 程序都应该有一个开发人员程序 — 无论您是公开 API，仅向合作伙伴公开，还是仅在内部公开。根据受众的不同，这些规定可能或多或少都很复杂。

开发人员门户

开发人员门户是开发人员计划的关键要素，是开发人员注册、访问和使用 API 的核心入口点。访问 API 对于开发人员来说应该是简单顺畅的。开发人员应能够快速开始使用您的 API。

TTFHW 是衡量这一点的最佳指标。您还应该考虑简化注册过程 — 更简单、更快捷、更好。建议的最佳实践是开发人员应该能够调用您的 API 来检查他们的行为（请求和响应），而不需要任何注册。此外，补充内容（如入门指南、API 参考文档或源代码）可以缩短学习曲线。

通过生态系统合作伙伴加速

作为 API 提供商，您在合作伙伴和供应商的生态系统中运营。这些合作伙伴通常拥有自己的内容分发和通信网络及方式。我们建议您确定联盟，这有助于提高 API 的采用率。通常，当 API 互补时，可以找到这种联盟，并在组合时为开发人员提供价值。

评估开发人员体验要考虑的问题：

1. 我们如何在前 5 分钟解释 API 的价值？开发一个关于最适合开发人员的 API 的价值主张的"电梯行销"。
2. 我们的 TTFHW 和 TTFPA 是什么，如何减少它？这是一种通过考虑端到端 TTFHW 来提高 API 开发人员友好性的强大方法。在考虑会影响开发人员体验的任意元素（如门户网站）以及 API 的各项变因时，我们建议您一定要考虑 TTFHW 和 TTFPA 指标。
3. 开发人员的入职流程是什么，是否做到了尽可能精简？这需要与您的 API 的用例保持一致。对于更敏感的 API 或数据访问，自然需要更高的安全级别，这就可能需要更多正式协议。对于别的一切，它应该非常简单直观，以便使早期开发人员获得成功（TTFHW）。
4. API 是否足够灵活以确保其对开发人员具有吸引力？如果您找到了正确的价值主张，并且开发人员注册了您的 API，那就太棒了。请记住，帮助他们取得成功不仅会留住他们，而且会增加他们的数量。
5. 如果开发人员遇到问题，我们如何提供支持？我们相信自助服务方法，这将有助于您扩展。好的文档、常见问题解答或论坛可以解决开发人员的许多问题。但是自助服务有其局限性，对于更深入的问题或其他复杂情况（如发票问题），应该有某种支持机制。
6. 我们的文档是否有助于创新？对于那些使用非常规用例或想要进行创新的开发人员，我们的文档能够提供哪些支持？任何事物都有可能激发伟大的创意。