摘要

  • LACNIC的注册API页面明确让使用者到Postman查看最当前的v3文档，但同一页面的端点表仍把ROA修改和删除写成按serialNumber进行的单条操作。
  • 页面链接的Postman集合则以organizationId为边界：GET、创建和PUT都面向组织的ROA列表，PUT的公开说明是用更新版本替换现有列表；撤销也通过组织级列表端点完成。
  • 整组期望状态可以带来原子性与幂等性。最小改进不是再加一层审批，而是让请求携带基线版本、显示预期差异、先做预检，并返回一次原子操作的结果与纠错谱系。

打开LACNIC的注册API页面，使用者会得到一个很合理的导航指令：v3最当前的文档放在Postman。生产环境的/lacnic/v3/info也会重定向到同一个公开文档。对于准备写客户端的人来说，这相当于告诉他，页面摘要若与可运行集合不同，应以链接过去的当前合同为准。

但页面自己的端点表仍提供另一套操作想象。创建和查询位于/rpki/roas，修改和删除位于/rpki/roas/{serialNumber}。在这张表里，ROA是一条有独立序列号的记录：找到它，改变它，其余记录并不进入这次意图。

公开的API Registro v3 Prod集合换了一个边界。GET和POST位于/lacnic/v3/rpki/roas/{organizationId}。更新也是对同一路径发PUT，说明文字要求以更新后的版本替换现有ROA列表。撤销则把一个列表POST到/lacnic/v3/rpki/roas-delete/{organizationId}。

差别不只是URL多了一个组织标识。单条修改问的是“这一个对象要怎么变”；整组替换表达的是“变更结束后，整个组织应当拥有哪些对象”。后一种请求中，没有出现在列表里的记录也可能成为一项决定。

先把整组写入的好处说完整

把列表当作期望状态，有清楚的工程价值。客户端先取回当前集合，在本地计算目标集合，再一次提交完整结果。服务器可以对整体做一致性校验，然后原子地写入。与连续发送新增、修改、删除相比，它减少了某一步失败后留下半成品状态的机会。

同一份目标列表还天然适合重试。前一次请求若已经成功，重复PUT理论上仍收敛到同一状态，而不是再制造一组副作用。对IP地址管理系统、路由安全自动化或定期对账程序而言，声明“最终要什么”往往比维护许多命令的先后顺序更稳。

LACNIC也完全可能在公开示例之外实施了强控制。它可以按组织串行处理写入，可以比较内部修订号，可以拒绝过时状态，也可以保存受保护的详细审计记录。认证后的界面还可能提供额外确认。本次研究没有使用账号或API密钥，也没有创建、修改或撤销任何ROA；公开示例没写出来，不能被扩大成生产系统一定没有。

因此，这篇文章不是在报告一次覆盖事故。它只指出：LACNIC指定为当前入口的公开合同，没有告诉自动化客户端，完整列表替换怎样与客户端读取的那一版状态绑定。

列表里的“没有”也会产生后果

设想同一组织授权了两个工具。工具甲读取当前ROA列表，准备为新前缀添加授权。工具乙更早读取过列表，正在纠正另一条授权的maxLength。两者都基于各自看到的状态生成一份内部完全自洽的完整列表。

如果甲先写入，乙稍后提交旧基线生成的列表，会发生什么？服务器可能合并，也可能拒绝，也可能串行化后要求重读，还可能直接以乙的完整列表替换当前状态。公开请求和响应示例没有给出答案。

在被检查的公开字段中，没有看到ETag、If-Match、修订令牌、基线列表哈希或其他条件写入语义；也没有看到dry-run、preview或预期diff。GET示例的响应头只展示Content-Type，正文是一个裸数组。更新示例没有公开响应头和响应体。这个范围只能证明文档没有展示，不能证明服务器内部不做冲突检查。

ROA又不是普通清单项。RFC 9582规定了当前ROA结构，它把IP地址空间与起源AS联系起来，并允许设置最大长度。RFC 9319说明，maxLength会影响哪些更具体前缀处于授权范围内。增加、收窄或遗漏一条ROA，会改变依赖方执行路由起源验证时所面对的证据。

这并不意味着LACNIC控制下游网络的路由决策。验证器何时获取对象、网络如何使用验证结果，都属于其他控制面。可注册层的影响边界仍然明确：LACNIC的API接受并发布授权状态，资源持有者决定意图。正因为两边各有权力，写入前提才应当被公开说清。

把三份文档收敛成一个运行合同

第一步是消除双重描述。注册API页面的端点表、/info指向的目的地和Postman集合，应当由同一个版本化定义生成。如果当前更新单位确实是组织级列表，摘要表就应这样写。如果serialNumber路径仍然受支持，则应说明它是单条变更、兼容层，还是最终也被转换成列表操作。

Postman元数据记录的2023年6月是发布日期，不是经过验证的最后更新时间。本次抓取使用了活动的latest版本标签。使用者不该通过猜测哪个日期更新来选择真相；三个表面都应显示同一个合同版本。

第二步是基线身份。GET返回一个不泄露内部结构的修订号、ETag或规范化列表哈希。PUT的含义变成：“只有当前列表仍等于我所读取的基线，才应用这份替换。”一旦基线过时，服务器返回冲突并保证没有变更。

第三步是预期差异。在真正写入前，preflight应列出将新增、修改和删除的条目，至少覆盖前缀、起源AS与maxLength。列表遗漏会从沉默的副作用变成可见选择。本地序列化不完整、旧缓存恢复、同时增删等问题，也能在改变注册状态前被发现。

第四步是原子结果。无论接受还是拒绝，都返回一次操作ID、合同版本、被接受的基线身份以及结果状态。重试可以沿用同一操作身份查询结局，而不是在超时后盲目再写。后来发生纠正时，新操作指向被替代的旧操作，不用当前状态悄悄改写历史。

最小字段 它关闭的疑问
路径与结构版本 客户端实际执行了哪套公开语义
组织与基线列表身份 这份期望状态基于哪次读取
新增、修改、删除差异 完整payload究竟想改变什么
预检结果 语法、授权与过期冲突是否在写前出现
原子操作与结果身份 整次转换是接受、拒绝还是可安全确认的重试
纠错指针 新决定怎样保留旧决定的来路

这样的对象并不厚重。它不要求把个人账号、密钥、反滥用规则或内部安全日志公开，也不需要委员会逐条批准ROA。它只要求运行代码公布自己已经使用的状态转换规则，并向受影响组织返回一份有边界的证明。

LACNIC已经把ROA管理变成可以自动化的服务，也公开了纠正错误ROA的重要性。现在需要闭合的是自动化自身的写入单位。网页不能一边把使用者送往当前文档，一边用另一种对象边界解释同一动作；若当前动作确实替换整组列表，就应让每次替换先证明它知道自己正在替换什么。

兼容性也应当进入合同，而不是留给猜测。如果旧客户端仍按序列号调用，文档可以给出明确的支持窗口、等价转换和退役条件；如果该路径只存在于旧表中，则应标记为历史描述。最危险的状态不是保留两种接口，而是两种接口都看似当前，却没有说明它们是否作用于同一个版本化状态。迁移说明可以很短：适用版本、最后支持日期、失败代码、回退方式和对并发规则的影响。这样，运行中的自动化不必在一次ROA维护窗口里临时发现自己读错了写入边界。

这种说明也能区分“接口仍可调用”与“接口仍是推荐合同”，避免兼容性被误读成长期权威。

来源