什么是GPT-4？完整指南
使用APIs.json和APIs.io的好处
2024-12-01
人是易忘的，API 的使用在很大程度上取决于发现。一般的 API 用例都是模糊的，在幕后不可见地发生，因此很容易想象这个过程只是奇迹般地发生了。
事实上，发现是这一过程的重要组成部分。为了使 API 顺利运行，它们必须是可发现和可理解的。其中很大一部分是确保制定标准，以记录 API 的最重要元素位于何处以及如何在更广泛的系统中使用它们。
下面，我们将研究一款名为 APIs.json 的工具，该工具可实现此功能。我们还将考虑其姊妹项目 APIs.io 的加入将如何改变游戏规则。我们还将考虑一些常规应用、挑战和注意事项，了解如何有效地大规模实施此工具。
什么是 APIs.json？
APIs.json是一种机器可读的规范，旨在为整个服务提供可发现性和操作清晰度。APIs.json 的功能类似于网站的站点地图，解释了操作系统、它们如何相互关联，以及重要的机器和人类可读文档在服务和系统生态系统中的位置。
APIs.json 的一个独特优势在于，这个“站点地图”索引不仅仅关注内部服务。内部、合作伙伴和公共 API 都在服务中整理和记录，从而可以全面了解 API 及其相关组件。
值得注意的是，APIs.json 还记录了人类可读的元素。虽然记录机器可读的部分是让系统更易于理解的有效解决方案，但提供人类可读的元素使其对人类最终用户来说具有独特的用途。这允许通过理解实现更好、更完整的集成。
作为一个例子，我们可以看看 Fitbit 的规格：
{
"name": "Fitbit",
"description": "Fitbit designs products that track everyday health and fitness, empowering and inspiring people to lead healthier, more active lives.",
"image": "https://www.fitbit.com/images/common/logo_with_trademark.png",
"tags": [
"fitness"
],
"created": "2015-01-01",
"modified": "2015-01-01",
"url": "https://www.fitbit.com/apis.json",
"specificationVersion": "0.14",
"apis": [
{
"name": "Fitbit Web API",
"description": "Fitbit designs products that track everyday health and fitness, empowering and inspiring people to lead healthier, more active lives.",
"image": "https://www.fitbit.com/images/common/logo_with_trademark.png",
"humanURL": "https://dev.fitbit.com/",
"baseURL": "https://api.fitbit.com/",
"tags": [],
"properties": [
{
"type": "X-blog",
"url": "http://blog.fitbit.com/"
},
{
"type": "X-blog-rss-feed",
"url": "http://blog.fitbit.com/feed/"
},
{
"type": "X-github",
"url": "https://github.com/fitbit"
},
{
"type": "X-twitter",
"url": "https://twitter.com/fitbit"
}
],
"contact": [
{
"FN": "Fitbit API Team",
"Url": "https://dev.fitbit.com/forum"
}
]
}
],
"maintainers": [
{
"FN": "Fitbit, Inc.",
"X-twitter": "fitbit"
}
]
}这是可以提供的额外人性化上下文的一个很好的例子。例如，简单地提及 API 的具体维护者和联系信息（如下所示）即可为“我应该联系谁来解决问题？”提供人性化答案，而且这样做不需要复杂性或昂贵的登录页面。
"contact": [
{
"FN": "Fitbit API Team",
"Url": "https://dev.fitbit.com/forum"
}
]
}
],
"maintainers": [
{
"FN": "Fitbit, Inc.",
"X-twitter": "fitbit"
}什么是 APIs.io？
进一步推进这一逻辑，基于 APIs.json 构建的工具APIs.io提供了更简化的发现。该服务本质上是一个 API 搜索引擎。就像 Google 和其他索引引擎最初都是以美化过的站点地图发现系统开始的一样，APIs.io 也把这种设计范式发挥到了极致。
APIs.io 并不是一个替代工具，但它可以成为发现新系统的有效方法。值得注意的是，它还提供了一个浏览区域来发现已编入索引的 API，从而实现更无缝的发现和利用。
使用 APIs.json 和 APIs.io 的好处
APIs.json 和 APIs.io 可以提供各种好处，例如实现更好的通信并使 API 更易于发现。拥有额外的数据还可以提高机器的可读性。以下是 APIs.json 可能实现的一些具体好处。
有效沟通
这些工具为开发人员与最终用户沟通提供了实质性的模式。开发人员可以实施这些工具来表示他们所设想的 API 设计，从而使沟通更加清晰。通过提供对 API 内部工作原理和模式的深入理解，将用户连接到特定的文档位置和假设，APIs.json 和 APIs.io 解锁了一种实质性的沟通模式，否则这种模式会因 API 用户范例的本质而变得模糊不清。
轻松发现 API
仅仅制作API 文档是不够的
这种易于实施也是一个巨大的好处。阻止大多数发现努力的原因是它们在开发过程中产生的摩擦。让事物可被发现
改进的 API 管理
完善技能的最简单方法是将其传授给其他人。同样，确保 API 设计有效的最佳方法是向其他人解释该设计。创建“API 站点地图”迫使开发人员考虑他们的系统是如何设计的。
通过深入研究 API，开发人员可以发现组织方面的问题，并且可以发现维护方面的问题。这使开发人员能够了解系统是如何设计的，如何改进，以及最终用户从外部角度如何理解 API。
促进机器可读性
机器可读系统易于集成和扩展，为此付出的努力可以随着时间的推移带来巨大的回报。机器可读集成意味着进一步实现互操作性的门槛较低，并为自动化和开发带来巨大好处。
从本质上讲，机器可读性类似于使用作弊代码，有助于消除系统孤岛。这里的一个重要部分是，人们在机器可读 API 规范方面投入了大量资金，并且实施起来阻力很小。有了OpenAPI、AsyncAPI、JSON、Schema等选项
社区与生态系统建设
API 用户很容易被视为一个整体，但事实上每个用户都有自己的考虑、顾虑和用例。这些用户需要一个支持网络才能有效地使用您的系统，而提供诸如 APIs.json 和 APIs.io 之类的发现引擎可以促进围绕您的 API 的社区开发。
这对长期 API 的使用和保留有着巨大的影响，但同时也为开源协作带来了附加好处。当系统相互连接并允许用户围绕用例进行整合时，这些系统将大规模释放巨大的好处。
挑战和注意事项
围绕 APIs.json 和 APIs.io 可能会出现一些担忧。首先，人们显然担心安全和隐私问题。在共享复杂的 API 详细信息时，开发人员应该考虑他们的 API 的哪些元素需要公开，哪些不需要。也就是说，采用适当的零信任 API 安全
开发人员可能还担心额外的流程。使用这些工具确实需要时间和资源投入，而一些开发人员（尤其是那些只提供单一 API 的开发人员）可能认为使用这些工具只是另一种成本，收益不大。
虽然不依赖其他系统的单 API 开发人员的评估可能准确，但开发人员从 APIs.json 和 APIs.io 中受益的程度实际上相当低。如果您出于任何原因需要公开您的系统并使其可被发现，这些工具是实现这一目标的好方法。因此，这个问题相对来说是自我选择的——如果您认为这个用例成本太高，那么它很可能就是这样。
结论
APIs.json 和 APIs.io 是出色的工具，可以帮助大多数组织获得切实的利益。通过一些基本的设计考虑和主动开发，它们可以在社区发展、自动化支持和新发现方面带来巨大好处。
原文地址：https://nordicapis.com/the-benefits-of-using-apis-json-and-apis-io/
同话题下的热门内容
