API产品需要API目录

目录的魅力：从纸页到数字世界

在数字时代，目录依然是一种持久的媒介，连亚马逊也会发送节日玩具目录。尽管如此，目录依然一季又一季地到来，尽管它们展示的产品随时可以在线购买。

目录的吸引力在于它们提供的发现机会。翻阅它们时，你不仅在心中构建了一张产品地图，了解了公司产品的种类和深度，而且即使你不立即下单，你也获得了有关公司及其产品的宝贵信息，这让你更有可能在未来考虑它们。零售商深知浏览的力量可以转化为销售，这就是目录持续流行的原因。

将这种体验与网上购物相比较。如果你有特定的需求，你可能会直接访问你知道可能拥有所需商品的网站。你可能会搜索它或直接导航到它，而无需停下来浏览其他类别。你可能已经对某个品牌有了信任，或者正在寻找损坏物品的直接替代品。你可以非常直接地导航到你想要的产品，点击购买。这种购物体验中并没有太多的“发现”。

你的API消费者与在线购物者非常相似。他们可能对自己的需求有明确的定义，并不完全了解所有可能性。API目录可以成为你展示他们可能不知道的API产品的工具，建议替代路径，并展示你的全套解决方案。特别是在竞争激烈的市场中，API目录可以帮助你克服发现的障碍，向开发人员展示他们未曾意识到的可能性。

什么是 API 目录？

很高兴您提出这个问题！API目录是一种多功能的工具，它们以不同的形式存在，但共同的目的是帮助用户轻松地找到所需内容。API目录作为一个界面，允许潜在用户浏览并探索按功能或其他用户关注点分组的可用API。

一个高质量的API目录具备以下几个关键特征：

• 可搜索性：它们提供搜索或过滤功能，使开发人员能够轻松缩小选择范围。这不仅帮助用户在多个选项中做出决策，而且避免了单一工具的局限。
• 信息丰富：每个API的目录条目都提供清晰、一致的快照，方便开发人员比较和选择。目标是为用户提供足够的信息，帮助他们构建API程序的思维导图。
• 引导性强：它们提供清晰的前进路径，包括高质量文档和“入门”资源的链接，以便开发人员能够快速实现他们所需的工具。

同时，我们也应该了解API目录不是什么：

• 非替代品：API目录不能替代详尽的文档。它们只是第一步，用户仍需深入了解如何使用API。
• 非推销工具：API目录是为寻找实用解决方案的开发人员提供的资源，它们必须真实、直接，避免废话。
• 非索引或数据库：虽然您可能在其他地方拥有所有API的列表，但目录是以用户需求为先的方式组织和呈现的。它们是为消费者设计的，以便更快地找到所需的解决方案。

公共与私人API目录：定制化的开发工具

无论您是在开发面向公众的API，还是构建服务于私有和合作伙伴的API服务架构，API目录都扮演着一个强大的工具角色。它们在任何情况下都能促进API的发现，并引导开发人员找到最合适的解决方案。

考虑API目录的受众和目的是至关重要的，这将帮助您确定哪些功能最为关键。对于公共API，目录应该易于被广泛的开发者发现和访问。而对于私有API，目录可能需要更注重安全性和对特定合作伙伴的可访问性。

明确您的API目录是为了服务广大开发者，还是为了满足特定组织或合作伙伴的需求，这将影响您在设计目录时应考虑的特性和功能。例如，公共API目录可能需要更强大的搜索和过滤功能，而私有API目录可能更注重权限管理和定制化访问。

通过精心设计您的API目录，您可以确保它不仅能吸引开发者，而且能够提供他们所需的信息，从而促进您的API被有效利用。

通过API目录推动公共API的货币化

开发人员常常长期使用某个工具而不自知其属于更广泛解决方案的一部分。这种现象并非仅限于API。实际上，在2007年之前，对Microsoft Office产品的90%以上功能请求已存在于产品中。用户一旦找到解决问题的方法，很少会进一步探索其他功能。API目录能够展示您的全系列API产品，使用户能够快速发现更强大的解决方案，实现更深入的集成，并挖掘更大的收入潜力。

尼尔森诺曼集团（Nielsen Norman Group, NNG）提出了几种策略，鼓励用户进一步探索，以下是API目录可以帮助实现的一些策略：

• 可见功能：NNG建议，“不要让人们搜索关键功能。”API目录的目的正是让选项显而易见，无需搜索。一个友好的浏览界面可以鼓励探索，并引导用户发现他们未曾考虑过的产品类别。
• 可见的标志：图标或缩略图网格，配合可扫描的文本，比纯文本列表更容易被潜在用户理解。视觉元素可以清晰展示API产品之间的关系，并突出重要特性和功能。强调可操作按钮而非文本的用户体验可以鼓励用户采取行动。
• 即时学习：API目录将实现细节放在需要时展示。向开发人员过早提供大量信息可能会造成反感。最有用的功能应在目录顶层可见，而系统要求和兼容性的关键细节应随时可用，但具体的文档细节可以留待开发人员完成浏览后再提供。
• 低承诺预览：让用户在安装或注册之前了解将会发生什么。API目录是展示快速GIF或图表的理想场所，使用户能够清楚了解功能。

通过这些策略，API目录不仅能帮助用户发现新的解决方案，还能提升用户体验，从而推动公共API的货币化。

为内部开发人员提供高效的API解决方案

尽管您可能主要处理内部私有API，认为API目录与您的需求不太相关，但实际上，API目录对私有API程序的作用与公共API程序有很多相似之处。即使您不打算将API作为收入中心，提高API的可发现性和突出最佳实践也能为您带来显著的好处。

在大型微服务架构中，API目录尤其有用。它们可以通过以下方式提高效率：

• 通过简化查找已有解决方案的过程，防止开发重复的API。
• 通过推广使用首选工具和版本，加强API治理。
• 通过宣传能节省时间的工具，合理分配团队资源。

对于内部团队而言，API目录充当着知识库和代码存储库之间的桥梁。它不仅是最佳实践的信息来源，也是帮助新API更有效集成的工具。与公共API目录相比，私有API目录可以更加定制化，以满足您对内部团队用例和开发生命周期的了解。您可以调整目录的内容和格式，引导开发人员遵循最佳实践，实现服务架构的一致性。

随着新的产品工程团队的快速发展，API目录还能减轻DevOps团队的负担。目录使开发团队能够快速识别组织内其他地方正在使用的API，从而利用其他团队的专业知识和工作成果。对于DevOps团队而言，目录是一种简单有效的方法来分享最佳实践和解答问题，减少对工程团队支持的变量。

探索API目录，激发创新灵感

如果您正考虑构建自己的API目录，不妨先看看一些成功的示例。这些示例不仅能给您带来灵感，还能展示API目录的最佳实践：

• Meta开发者文档：Meta（Facebook的前身）提供了丰富的API资源，其目录设计强调了品牌和清晰的分类，便于快速浏览。
• Twilio API参考：Twilio的目录在首页提供了精选的API信息，并提供了基于用例和开发平台的筛选功能，帮助用户迅速缩小选择范围。
• Slack API：Slack以简洁的类别组织API，并为最常用的API提供了详细信息。它的设计鼓励用户探索，同时保持了侧边栏的简洁性。
• 亚马逊销售合作伙伴API：虽然找到这个目录可能有点困难，但一旦到达，开发者会发现一个清晰、易于导航的目录，它提供了与亚马逊电商集成相关的所有API。

接下来，我们将进一步探讨API目录能为您的API团队带来的好处和局限。同时，当您使用API、开发者工具、应用程序和网站时，请留意那些促进发现的用户体验。什么样的体验能让您更深入地了解并探索产品的新用例和功能？

您的API和DevOps团队构建的产品值得被那些能够最有效地使用它们的开发者发现。将您对激发发现的观察应用到您的API目录中，可以成为改善开发人员体验的有力工具。

文件链接来自：https://blog.stoplight.io/api-products-need-api-catalogs