什么是API开发者门户？最佳实践与示例

什么是开发门户？

根据DevPortal Awards的主要赞助商Provonix的定义，开发门户如下：

“开发门户——通常简称为DevPortal——是一组API、SDK或其他交互式数字工具与其各种利益相关者之间的接口。”

更简单地说，开发门户是提供公司所有服务和解决方案界面的网站。它们是为多种利益相关者（不仅仅是开发人员）提供的资源。

普通网站与开发门户之间的一个关键区别在于，普通网站包含静态内容，而开发门户包含动态内容，这些内容会不断更新。

与维基不同，开发门户是外部的，同时也可作为内部利益相关者的资源。由于维基是内部的，它们常常被忽视，并随着文档优先级的转移而过时。由于开发门户是外部的，其维护优先级通常高于内部维基。

调查强调了高质量开发文档的重要性。SmartBear的《2019年API现状报告》中一项调查将“准确且详细的文档”列为API最重要的特性之一，排名第三。开发门户是SaaS公司共享文档的主要方式。

开发门户与营销网站之间的关系也有些模糊。有时，企业会有一个营销网站，链接到其开发门户。其他公司，如纯SaaS公司，可能只有开发门户，而没有专门的营销网站。

那么，为什么公司应该投入时间和金钱来增强其开发者门户呢？一个好的开发者门户能够传达平台及其服务的价值。它描述了平台如何解决具体的业务挑战，而无需使用营销/广告的夸张言辞。

虽然开发文档常常与开发者门户相关联，但开发者门户不仅仅是开发人员访问其API参考文档的地方。开发者门户应允许所有业务相关方（无论是技术人员还是非技术人员）了解并体验平台。

在下一部分，我们将探讨这些特性。

以下是有效开发者门户的特性。

虽然开发文档是开发者门户的一个重要方面，但它并非全部。理想情况下，开发者门户应作为访问公司产品和服务所有接口的中央资源。它们可能不仅限于API/服务。其他接口包括图形用户界面、无代码接口，以及面向无法获取开发资源的用户的低代码界面，如小部件。

虽然REST API是开发者门户的关注焦点，但也可以记录其他类型的API，例如物联网API、语音助手API、GraphQL API或原生库API。通常，一家公司会提供一系列服务，而不仅仅是REST API。在一个开发者门户上看到数十种不同类型的开发文档是有可能的。除了API之外，开发者门户上可提供的其他技术解决方案还包括客户端库或SDK。有时，开发者门户还可以展示由开发人员构建的解决方案。

清晰的业务模式

用户应能理解平台所处的行业及其提供服务的总体概况。解决方案应按其所属领域或所解决的具体业务挑战进行分类。用户应能对提供的所有解决方案形成一个心智模型，了解它们如何在一个统一的平台中协同工作。

服务在更大背景下的相互关系，可以通过文字、视觉图形或开发者门户本身的结构来传达。

透明的定价

客户应能非常早地了解平台的定价模式。定价结构应阐明其如何解决特定问题，以及不同定价计划之间的差异。

开发者门户应回答以下问题：

• API 产品如何实现盈利（直接 vs 间接）？
• 可用定价计划之间有何差异？是否有按需付费、自助服务或免费增值计划？
• 每个定价计划是否有速率限制？

定价计划与产品入门流程相关，因为用户在必须付费前通常只能使用有限数量的功能。透明的定价有助于推动潜在客户向实际客户的转化。

内容“分层”

分层架构是一个从软件开发借鉴而来的概念，可以应用于内容组织。

以下是一个关于如何对开发者门户进行分层的示例：

• 开发者门户的顶层是着陆页面，用户在此理解业务模式、了解所提供服务/解决方案的概览以及常见用例。
• 中间层是按解决的业务挑战分组的解决方案类别。
• 底层则是这些解决方案的文档，包括任何入门教程和API参考。

当然，这些只是示例。根据业务需求，可能还需要其他层级。

分层架构确保了不同解决方案间的一致性。用户能了解到每个部分应包含何种信息。

与主着陆页面类似，每个解决方案都应拥有自己的着陆页面，以传达该解决方案的价值。解决方案页面应提供对解决方案概览、用例、入门详情、快速开始和技术参考材料的快速访问。

采用分离平台不同组件的分层架构，可以充分利用链接功能。你可以从业务部分链接到技术部分，反之亦然。例如，阅读解决方案概览的业务分析师可能只想查看业务信息，同时也能通过点击链接到技术文档来了解更多。链接功能也让开发者能够直接跳转到技术细节，而无需困在阅读业务材料中。

一致的设计

设计元素如果运用得当，其意义远超美观。设计元素能提升可用性，并与内容质量相辅相成。一个设计精良的开发者门户，其设计元素应能支持用户在发现、了解和与平台互动过程中的用户旅程。

有效的设计能够强化整体品牌。品牌不仅决定美学选择，还影响内容的撰写方式。文档编写应使用相同的风格和语调，并在所有解决方案中保持一致。

可发现性

开发人员门户的首要目标是让用户能够轻松发现其业务挑战的解决方案。在开发人员门户上查找信息的过程应当是无障碍的。

开发人员门户中信息的“可发现性”由其结构和搜索/过滤功能决定。开发人员门户应构建其文档门户的结构，以便用户能够轻松了解可用的解决方案范围。应能按类别轻松筛选解决方案，以缩小可能性列表并排除干扰。

在API参考中，应能按资源、端点、参数和模式进行搜索和过滤。

迎合非技术用户

SaaS公司也认识到，除了从头开始构建利用服务的应用程序外，还有不同的方式来使用技术产品。例如，平台可能提供只需极少编码即可轻松添加到网站的小部件。无代码或低代码解决方案打破了谁能体验技术产品价值的障碍。

最佳的开发人员门户为每个能力级别提供入职旅程。例如，技术用户可以从头开始构建应用程序，而非技术用户可以下载模板开始尝试。

入门指南

用户入门流程通常是用户首次使用解决方案的体验。如果在入门过程中遇到阻碍，潜在客户可能在完整演示 API 之前就放弃了。在设置好账户并获取凭证后，“开始使用”部分会引导用户完成与解决方案（例如一个API）交互的端到端流程。

API 参考

💛🧡🧡客户评价：Baklib用户界面非常简单，技术和非技术团队均可访问。他们的编辑器允许技术和非技术文档的出色渲染。他们提供定制支持的客户支持团队和技术团队解决了我们的特定需求，基于他们的低代码在几个小时内完成。

API参考是供开发者阅读的简洁而详细的指南，用于理解API。有效的API参考页面允许开发者通过结合搜索和过滤功能，快速找到资源、端点、字段或模式的信息。

“试试看”功能提供了一种动手与API交互的方式。最先进的开发门户会根据用户的账户详情，自动用其凭证填充“试试看”小部件。

社区

社区通常是故障排除的第一级支持。许多开发门户都设有社区页面。有些公司使用Discord频道或公开的Slack频道等工具，在不同类别下主持讨论。

如果用户可以通过在留言板上提问找到答案，他们就不需要联系支持团队。如果公司参与到社区中，可以将问题记录为错误或需要改进的文档。

社区可以超越讨论论坛的范畴。它们可以促成小型聚会或大型会议，从而推广一个平台。

更新

随着平台发展而定期发布更新，是可靠性和可信度的标志。发布说明、法规和变更日志都是补充文档的例子，它们能让用户了解最新的变化。

在编写任何一行代码之前，构建开发者门户需要许多步骤。假设商业模式是可靠的，就应该进行开发者体验设计，使门户的各个方面保持一致，为用户提供最佳体验。

明确商业模式

开发者门户的结构应反映企业及其解决方案的结构。如果开发者门户未能清晰地传达业务结构，用户就会感到困惑。

保持门户的最新状态需要整个组织的协作，仅依赖一个团队是无法成功的。所有团队都有责任保持其领域内容的更新并及时响应反馈。

进行开发者体验设计

开发者门户与开发者体验的概念密切相关。与普通的用户体验设计不同，DX是为那些经常使用没有图形用户界面的技术产品（如API、客户端库或SDK）的开发者量身定制的。由于没有用户界面，文档必须告诉开发者如何与产品进行交互。在很大程度上，文档在开发者或其他业务利益相关者如何“体验”一个技术产品方面起着重要作用。

同样地，公司聘请UX设计师，也应该聘请DX设计师来打造开发者使用开发者门户的体验。DX“战略师”是管理开发者门户生命周期的核心角色。这位战略师负责监督流程、标准和工具的变化，这些变化会影响到各个解决方案团队。该战略师确保设计、美学、结构和内容协同工作，为开发者创造愉悦的体验。

战略师会创建访问门户的用户画像，并设计用户旅程以满足他们的需求。例如，理想情况下，应为技术用户和非技术用户设计独立的入门用户旅程。

构建门户结构

在建立信息架构时，必须确定所有解决方案都需要哪些信息。例如，每个解决方案都需要特定顺序的入门指南、使用案例和API参考。如果各解决方案间的文档保持统一，Baklib开发门户的用户就能明确了解他们将获得什么。

分层架构结合链接功能，能让用户更轻松地从顶层（业务详情）导航到底层（技术细节），反之亦然。

建立治理计划

很多时候，每个解决方案由不同的团队管理。为了在整个门户提供一致的体验，必须建立促进内容组织和写作指南一致性的标准。

建立治理计划需要协作制定标准，并获得各业务部门的认同以全面完成计划。每个团队都应负责遵守这些标准并承担相应责任。治理计划应统一语言和语调、风格和格式，以及从业务材料到API参考的内容组织。最后，治理计划应强化品牌形象。

通过入门指南降低学习门槛

在传达了Baklib作为整体的商业价值后，应立即引导用户前往独立的解决方案页面，在那里他们可以试用API、服务、客户端库或SDK。这些页面的核心位置应提供指向入门流程的链接，以便用户能尽快体验产品。

对于"入门"教程，请选择一个简单的用例，让用户能够从头到尾理解解决方案。

准确记录API参考

是否所有API组件都得到了准确记录？每个资源都记录了吗？单个端点和模式是否被完整描述？每个字段描述是否说明了其用途、所选值的效果以及与其他系统字段的交互？整个规范中相同字段的定义是否标准化？API参考的内容应遵循API风格指南，该指南确定了API所有组件的标准。遵循风格指南可确保API参考文档的一致性和完整性。如果没有准确详细的参考信息，所有花哨的功能都毫无用处。

记录技术参考信息通常是改进整体文档的第一步，因为在编写教程之前，技术信息必须扎实可靠。

配置搜索/筛选功能

一个开发者门户网站可能包含数十个对应不同解决方案的页面。除了清晰的站点结构外，强大的搜索功能可以提高可发现性，使用户能够找到解决其特定业务问题的方案。

应提供一个API探索器，用户应能够搜索和筛选提供的解决方案列表。

在API参考文档中拥有强大的搜索功能非常重要。API参考上的搜索栏应允许对构成API的所有组件进行精细搜索。

建立社区

从早期开始，您就应该考虑如何围绕您企业的解决方案培养和发展社区。这既是一种长期的支持策略，也是产品采用的策略。

其他更微妙的社区形式是邀请开发人员注册新闻通讯，以保持沟通渠道畅通。

启动反馈循环

在开发门户中，用户应该有许多提供反馈的机会。例如，每个API参考部分都提供评级机制，并可以选择提供自由格式的反馈。

另一个反馈来源是社区。一个积极使用产品并发表帖子的社区，本身就是一个反馈源，甚至无需主动索取。

提供案例研究和参考

当案例研究与使用产品的客户推荐相结合时，会更具说服力。案例研究可以展示常见的业务挑战，以及如何通过某个平台解决这些问题。用户可能会认同某个案例，并立刻明白他们如何使用该工具来完成特定任务或解决他人遇到过的问题。

另外，请查看我们关于开发文档清单的博客文章。

定期发布更新和状态

随着平台的演进，定期发布更新是可靠性和可信赖性的标志。

相关阅读： 什么是 Open API？优点、缺点及示例

最佳开发门户

以下是按类别划分的最佳开发门户。

最佳API参考：Stripe

Stripe是一个支付处理平台，拥有设计精良且直观的API参考文档。

API参考文档必须能让开发人员在大量的技术细节中快速找到所需信息。

Stripe采用单页网站设计，允许您通过点击左侧导航链接、向下滚动页面或执行搜索来快速导航到不同部分。

Stripe API参考的一些功能包括：

• 可折叠内容 - 几乎所有的内容都是可折叠的，包括字段描述、表格、架构等。这样您可以专注于所需的信息，而不会有过多的杂乱。
• 可切换的编程语言 - 您可以通过一个按钮全局更改代码示例的编程语言。此外，您还可以通过点击复制到剪贴板按钮轻松复制代码示例。
• 开发者友好的深色模式 - 对于喜欢类似代码编辑器的深色背景的开发者来说，这是一个很棒的功能。
• 广泛的链接 - 每当需要深入解释时，API参考会提供指向概念文档的链接，以获取背景信息和教程。
• 多个反馈点 - 您可以为每个部分提供反馈，包括在给出评分后撰写自由格式的文本。
• 高级搜索和筛选 - Stripe的高级搜索允许您对OpenAPI的几乎所有组件进行筛选。

最佳可查找性：Visa

Visa开发者平台让您能够通过API利用Visa网络的力量。

使这个平台脱颖而出的是，筛选可用API和服务以找到您需要的那个是多么容易。从他们的产品浏览器中，您可以通过多个类别筛选API列表。筛选功能让您能够快速找到解决您特定业务挑战的API。

在筛选列表中，每个API“卡片”都包含了服务的简短描述，随后是指向该API概览或文档页面的链接。概览页面涵盖通用的业务信息，而文档页面则提供API参考。您可以根据需要快速定位所需的文档，无论是用于入门还是查阅技术参考。 此外，您还可以从“用例”页面中找到适用于您情况的用例，其中包含推荐和案例研究。

最佳编码教程：Fiserv

Fiserv的开发者门户在提供如何实现Fiserv API的逐步示例方面表现出色。

“配方”是针对不同用例的教程，提供多种语言的代码示例。每个配方都会引导您完成特定任务的过程，过程中的每个步骤都有注释，以提供更多上下文。

当从主文档中访问这些配方时，其优势尤为明显。主文档在需要逐步指导时会链接到特定的配方。这种将代码示例集成到文档中的方式，使Fiserv的平台非常以用例为导向。

最适合非技术用户：platformOS

platformOS是一个开发“平台即服务”，强调性能、可靠性、灵活性、安全性和可扩展性，并涵盖多种用例。

platformOS是最容易上手的平台之一，因为它迎合了所有技术水平的用户。它将用户分为三种不同的类型：非技术用户、半技术用户和技术用户。每种用户类型都有其入门流程。

• 非技术用户可以点击一键安装来注册账户，并按照简单的设置向导创建一个演示博客网站。
• 半技术用户可以点击沙盒链接从GitHub克隆一个演示站点。然后他们可以按照“Hello, World!”指南来理解发送请求和读取响应的基础知识。
• 技术用户可以直接通过点击构建您的第一个应用，使用platformOS平台创建一个应用。他们可以按照文档设置开发环境，然后部署和测试他们的应用。

platformOS允许非技术用户体验平台，同时为技术用户提供了一条快速从头开始构建应用的途径。

📝 快速阅读

摘要

SaaS公司正在大力投资其开发者门户。公司现在认识到其开发者门户上的内容作为影响采用的外部资源具有潜在的高价值。创建一个有效的开发者门户需要整个组织协调一致，并需要一个自上而下的治理计划来强化品牌。