API标准即数据标准

除了那些过去二十年忽略技术趋势的人，其他人都意识到——并且可能正在使用——基于服务的架构，无论是微服务、领域驱动、模块化、集成、数据还是其他形式。从基于服务，我们演进到API优先，其中API是一等交付物，所有解决方案都围绕其构建：前端、后端、移动端、外部集成等。API旨在在其他开发工作开始之前实现，即使初始实现是存根或虚拟代码，以允许其他工作开始。API优先围绕合同展开。

我们软件工程师关注API可能被实现的多种方式，但消费者不关心：消费者的关注点是发布的API合同是否按定义履行。除了天生的好奇心，消费者不关心也不需要知道您为实现付出的血汗和泪水。他们的关注点是适用性和整体正确性。

组织通常花费大量精力定义其API标准，并应用这些标准到其API中，以增加在API优先世界中成功的机会。我将API标准视为消费者的数据合同，类似于为（希望）改善组织内数据处理实践而定义的数据标准。是的，API功能通常超出简单的CRUD操作，并共享许多特征，但它由组织内的不同组创建和维护。

什么是数据标准？

数据标准，也称为数据建模标准，定义组织定义和管理关键任务数据的方法论，以确保在整个组织中的一致性、理解性和可用性，包括软件工程师、数据科学家、合规性、业务所有者等角色。

每个组织有不同的目标和对业务重要的非功能性需求，因此不存在通用的、包罗万象的标准。过去二十多年的方法论变化使软件工程团队能够及时建模其数据解决方案，通常减少实际数据团队（如果存在）的参与。无论如何，当组织数据标准被创建（并强制执行）时，其组件通常包括：

命名：用于描述主题领域及其单个数据元素时的一致性和易于理解的术语或方言，可能是行业标准、业务特定或通用的。可接受的缩写可能是命名标准的一部分。偶尔，标准定义内部数据库元素的名称，如索引、约束和序列生成器。
数据域：大多数数据元素被分配一个数据域或类，定义其特定的数据实现，例如：id是UUID主键；code是五个字母数字字符；percent是最大四位小数的浮点数；name包含5到35个字母数字字符。
结构：由后端数据库决定——即关系数据库中的第三范式与文档导向NoSQL中一起访问的数据存储在一起——持久化数据可能截然不同，尽管局部决策仍然存在：业务与系统生成的主键；JSON子文档的数组、键或集合；性能和扩展的数据分区；开发优化的更改。一个解决方案在关系数据库之上实现了自己的数据字典，通过牺牲工程简单性来简化客户可配置性。
验证：超出数据类型或数据域提供的数据检查和验证，通常是业务或行业特定的，例如：一个医疗设施由一个或多个建筑组成，或注册用户必须包含验证的电子邮件地址、公司地址和职位。当正确实施时，数据验证提高数据质量并增加数据对组织的价值。

这不是一个包罗万象的列表，因为具有更成熟数据实践的组织通常有更多组件或覆盖领域。不幸的是，在我看来，当前青睐的方法论通常在功能开发期间淡化定义/应用正式数据标准；然而，这是另一个时间的讨论。

深入探讨

用现实生活中的例子最容易展示API和数据标准的相似性，因此让我们使用GitHub端点。为演示目的创建一个提交状态：

具有仓库推送访问权限的用户可以为给定SHA创建提交状态。注意：每个仓库内每个sha和上下文有1000个状态的限制。尝试创建超过1000个状态将导致验证错误。 “创建提交状态”的细粒度访问令牌此端点适用于以下细粒度令牌类型：

GitHub App用户访问令牌 GitHub App安装访问令牌细粒度个人访问令牌

细粒度令牌必须具有以下权限集：

URI

URI及其路径名包含术语（名称）和数据：

POST主要用于创建数据，在我们的示例中，将（创建）提交状态附加到现有提交；
仓库的标准缩写是repos；
repos和statuses是复数而不是单数（通常需要大量讨论和烦恼）；
{owner}、{repo}和{sha}是调用者提供的值或路径参数，以指定此调用更新的提交；
{owner}和{repo}定义为不区分大小写。

注意，owners没有明确调用，例如假设的/owners/{owner}/repos/{repo}/statuses/{sha}。因为GitHub仓库总是由其所有者和名称标识。GitHub工程师可能得出结论，包含它是不必要、多余或混淆的。

头部

调用者（消费者）通过在HTTP头部中指定日期来声明要使用的API版本。或者，一些API标准在URI中将版本指定为序列号；可能还有其他格式，我不知道。

头部还可能包括支持非功能性需求的数据，如可观察性。

请求体

请求体提供支持此API调用的数据，在这种情况下，创建提交状态所需的数据。要点：

仅顶层JSON文档，无子文档；
state是具有四个有效值的枚举值；
target_url以后缀_url结尾，暗示期望有效的URL；
description是简短描述，但什么构成简短未指定：是20、100还是1024字符？

请求体通常为HTTP POST、PUT和PUT调用提供，具有任意大小和复杂性，基于调用的需求。

调用响应

所有API返回HTTP状态码，大多数返回表示结果的数据（DELETE是预期例外）。对于我们演示目的，成功的API调用将是创建的提交状态。不成功的API调用（非2xx）通常包括有助于调试的错误详细信息。

我们API的响应清楚地显示了应用的标准：

一致的_url数据域用于GitHub返回的各种URL，即target_url、avatar_url、followers_url等；
_id数据域用于唯一标识符，即node_id、gravatar_id和独立的_id；
creator子文档是（完整的？）用户对象；
更多复数：followers_url、subscriptions_url、organizations_url、received_events_url。

查询参数

我们的演示API没有支持查询参数，但检索数据的API通常需要这些用于过滤、分页和排序目的。

最终思考

API标准和数据标准比许多工程师愿意承认的更加相似，具有相似的问题和目标。如果这些标准为一致性而对齐，而不是在真空中创建每个，组织将受益。尽管API支持的用例通常超出基本CRUD操作——并且一些API不会导致持久化数据——但API消费者将合同视为数据驱动的。因此，将数据标准的众所周知原则应用到您的API标准中，增加API的一致性和完整性，减少开发时间，并减少错误。

最初发布于https://scottsosna.com/2025/07/07/api-standards-are-data-standards/。