什么是API？软件接口的实用指南
无抓取抓取API提供特定任务的接口，返回用于应用程序工作流的结构化公共网络数据。
简而言之
- API是一个定义好的软件接口。 它暴露了命名的能力和规则，因此一个组件可以使用另一个，而无需了解其内部实现。
- 契约比传输更重要。 API可以是库接口、操作系统调用、本地接口或远程网络服务。
- Web API通常交换请求和响应。 端点、操作、参数、身份验证、表示、错误和限制形成可用契约。
- REST、GraphQL、RPC和SOAP是远程API的方法。 它们以不同的方式组织操作和消息，应该根据系统的限制进行选择。
- 成功的集成像成功一样，有意识地处理失败。 验证、授权、配额、超时、版本控制和可观察性是设计的一部分。
API意味着应用程序编程接口
应用程序编程接口是一组规则和暴露的能力，软件可以调用或使用。接口将实现细节隐藏在一个稳定的边界后面。调用者需要知道存在哪些操作，接受什么输入，产生什么输出或者效果，以及如何报告错误。提供者可以在保持该契约的同时更改内部代码，从而允许双方在更少协调的情况下发展。
API在Web之前就存在，并且比HTTP端点更广泛。编程语言库暴露函数、类和类型。操作系统暴露系统调用。设备驱动程序暴露对操作系统的操作。远程服务通过网络暴露消息。 NIST API词汇表 将API描述为一个定义良好的访问点或库函数，而MDN的基于Web的定义则涵盖应用程序可用的代码特性和规则。
Web API调用如何工作
当处理路径明确时，什么是API更易于操作。以下阶段展示了可以收集证据的地方以及政策如何改变结果。
发现和契约
消费者阅读文档或机器可读描述以了解基本地址、操作、参数、表示、身份验证方法、限制和错误模型。契约可能是非正式的文档或正式的支持验证和生成工具的模式。
请求处理
客户端构建请求，在需要时进行自我识别，并在接口定义的位置发送输入。网关或服务对调用者进行身份验证，授权操作，验证输入，应用策略，调用应用逻辑并创建响应。
响应解释
客户端评估传输状态、应用程序错误、元数据和返回的表示。然后，它将结果映射到本地类型或用户可见的行为。正确的客户端不假设语法上有效的响应意味着请求的业务操作成功。
API契约的部分
围绕什么是API的词汇涵盖架构、数据和操作。这个表保持那些责任分开，以便设计审查可以提出正确的问题。
| 概念 | 意义 | 实际信号 |
|---|---|---|
| 端点或可调用的 | 操作如何或在哪里被地址。 | 一个URL、函数名、方法、主题或命令。 |
| 操作 | 提供者暴露的能力。 | 读取记录、创建任务、转换数据或触发操作。 |
| 输入模式 | 接受的参数和主体形状。 | 名称、类型、必需字段、范围和默认值。 |
| 输出模式 | 返回的数据和元数据。 | 字段、嵌套、可空性、分页和状态。 |
| 政策 | 围绕访问和消费的规则。 | 身份验证、授权、配额、成本和可接受使用。 |
API所能实现的
关于什么是API的实际案例始于系统必须执行的工作。这些示例展示了该要求如何改变接口或网络决策。
产品集成
移动、网页或桌面客户端可以使用后端功能，而无需嵌入后端实现。
自动化
计划任务和代理可以通过记录的软件边界执行可重复操作。
平台生态系统
合作伙伴可以根据提供者故意暴露的功能构建扩展和工作流程。
内部模块化
团队可以将系统划分为带有明确所有权和变更边界的服务或包。
如何在集成前评估API
从适合度开始。确认API暴露实际工作流程所需的操作和数据，包括过滤、分页、排序、新鲜度和区域行为。检查表示是否包含稳定的标识符，以及缺失字段是否被省略或返回为null。一个经过打磨的示例不能替代完整的契约。
检查操作规则。认证和授权决定谁可以调用什么。配额和负载限制决定可行的工作负载形状。版本控制和弃用政策决定维护风险。错误文档应区分调用者错误、访问失败、配额条件和提供者故障，以便客户端可以采取安全且有限的行动。
将安全性作为接口的一部分进行审查。 HTTP语义规范 定义请求方法、状态概念和许多web API使用的表示元数据。传输加密保护传输中的数据，但应用程序仍然需要最小权限凭证、输入验证、秘密存储、审核记录和防止暴露敏感字段的控制。
应避免的API集成错误
- 将示例视为完整的模式。 示例可能会省略生产流量中包含的可选、可为null、分页或错误字段。
- 将凭证嵌入源代码。 秘密应来自受保护的运行时机制，并应根据提供者政策进行范围限制和轮换。
- 忽略幂等性和重复效果。 超时的创建请求可能已经完成，因此变更设计需要一种记录结果的文档化方式。
- 假设每个成功都相似。 有些接口返回接受的工作、部分数据、警告或异步任务标识符，而不是最终结果。
- 耦合到未记录的行为。 内部字段顺序、附带头部和未列出的端点可以在没有兼容性保证的情况下更改。
Web数据工作流程中的API
一个结构化的API可以通过直接返回记录来消除工作流程中的浏览器解析。当提供者暴露所需数据并且条款允许预期使用时，这样的做法是有效的。当没有合适的结构化接口存在且信息是公开可用的时，集合系统可能需要一个HTTP获取或浏览器渲染步骤，然后进行提取和标准化。
保持获取、转换和存储作为独立边界。获取组件应保留源状态和相关元数据。转换应验证字段并使缺失值明确。存储应使用稳定的标识符并记录治理所需的来源。这种分离可以防止源格式的变化静默破坏下游数据。
记录客户端契约与提供者契约：使用了哪些操作、哪些字段是必需的、预期的体量是多少、凭证如何提供、以及什么证据标示完整结果。测试应涵盖代表性的成功和错误负载，而不依赖于私有实现细节。
什么是API审查清单
使用这些检查将什么是API的定义转化为开发者、操作员或审查者可以重现的实施证据。
- 重申边界。 对于什么是API，识别调用者、提供者、路径和标记完整结果的确切事件。
- 验证核心声明。 用实施及其文档确认这一声明：API是一个定义的软件接口。它暴露命名的能力和规则，以便一个组件可以在不知道其内部实现的情况下使用另一个组件。
- 追踪机制。 观察发现和契约、请求处理、响应解释，并记录每个阶段由哪个组件拥有。
- 检查最接近的区分。 记录为什么在这个系统中，端点或可调用意味着“操作被指向的地方或方式”。
- 测试一个代表性的用例。 使用产品集成和现实数据、位置、体量和权限边界。
- 防范已知错误。 审查“将示例视为完整的模式。”并添加一个接受检查以捕捉到它。
- 限制工作负载。 为《什么是API》设定主题相关的限制，包括有效载荷、并发性、执行时间和适用的存储输出。
- 记录决定。 解释为什么《什么是API》适合这个边界，并列出将来证实不同方法的证据。
结论
《什么是API》应该描述设计中可测试的部分，而不是作为邻近行为的宽松标签。审查应保持这一中心决定：API是一个定义的软件接口。它暴露命名的功能和规则，以便一个组件可以在不知晓其内部实现的情况下使用另一个组件。它还应防止将示例视为完整的架构，并保持《什么是API》的访问在接口或网络的文档政策之内。
准备好构建您的网络数据工作流了吗？
将可测量的《什么是API》获取或集成步骤与上述验证和存储实践相连接。
今天注册并获得 $5的免费信用 — 无需信用卡.
领取您的$5信用 →常见问题
API代表什么？
API代表应用程序编程接口。它是软件向其他软件暴露功能的定义边界，包括函数、类型、操作系统调用、设备操作和远程服务消息。
每个API都是web API吗？
不是。Web API使用网络技术进行通信，通常跨网络，但库、操作系统、数据库和硬件也暴露API。共同的理念是文档化的接口，而不是特定的协议。
什么是API端点？
API端点是一个可寻址的位置，通过它，客户端访问远程API功能。在HTTP API中，通常是一个与方法和文档输入结合的URL，尽管确切的操作也可能依赖于头信息或请求体。
API总是返回JSON吗？
不。API可以返回JSON、XML、HTML、二进制文件、特定于协议的消息或语言本地值。JSON在Web API中很常见，因为它紧凑、基于文本并且得到广泛支持，但接口合同定义了表示。