Summary

  • LACNIC’s Registration API page directs operators to Postman for the most current v3 documentation, yet its own route table describes ROA modification and removal at an item-addressed serialNumber path.
  • The linked collection instead documents an organization-scoped PUT that replaces the existing ROA list, and a separate organization-scoped revocation route. The checked public examples do not show the base version, intended diff or stale-write condition for that replacement.
  • Whole-list desired state can be simple, atomic and idempotent. A versioned executable contract would preserve those advantages while letting an operator prove which list was inspected, what was intended to change and whether the server accepted that exact transition.

An operator who lands on LACNIC’s Registration API page receives a sensible instruction: for the most current version 3 documentation, use Postman. This is more than a convenience link. It tells the reader which public surface should govern implementation when prose elsewhere has aged.

The table on that same page nevertheless gives a different mental model for ROAs. Creation and retrieval sit at /rpki/roas. Modification and removal sit at /rpki/roas/{serialNumber}. The object appears individually addressable. Find its serial number, act on that record, and leave the rest of the collection outside the operation.

The production /lacnic/v3/info route currently redirects to the same published Postman document. In the linked collection, API Registro v3 Prod, retrieval and creation are organization-scoped at /lacnic/v3/rpki/roas/{organizationId}. Update is a PUT to that route. Its description says the existing list is replaced with an updated version. Revocation is a POST of a list to /lacnic/v3/rpki/roas-delete/{organizationId}.

This is not a cosmetic difference between two ways of writing a URL. It changes the unit of intent. The website table describes an item. The collection describes a set.

The best case for replacing the set

There is a strong operational case for the collection design. A client can retrieve the organization’s present list, calculate the desired list and PUT that complete state. It does not need to orchestrate a chain of creates, edits and deletions whose partial success leaves an intermediate configuration. The server can validate the set as a whole and commit it atomically. Repeating the same request can naturally converge on the same result.

This is the attraction of declarative interfaces. The client states what should exist, rather than prescribing every internal step. For an organization managing many authorizations through IP-address management or routing-security automation, one coherent desired state may be easier to review than a queue of item-level commands.

LACNIC may also protect the operation in ways that the public example does not reveal. It may serialize writes for an organization, compare an internal revision, reject conflicts, retain a detailed protected history, calculate a diff before commitment or give authenticated users additional tooling. No authenticated request was made for this research. The public documents do not establish that production lacks those controls.

That defense matters because a missing field in an example is not an incident. It is a limit on what an implementer can learn before holding credentials and testing live state. The right criticism is therefore narrower: the public contract that LACNIC itself identifies as current does not show how a complete replacement is bound to the list on which the client based it.

A full list carries absent records as decisions

An item-level update says, in effect, change this object. A full-list replacement says something more: make every object in this payload the organization’s resulting set. An omitted entry can therefore become as consequential as an added one.

Imagine two authorized automation processes that read the same organization at different times. One prepares a new ROA for a fresh prefix. The other corrects maxLength on an existing authorization. Each submits a complete list based on the state it observed. If the public contract contains no visible base version or conflict condition, neither client can tell from the documentation alone whether a later write will merge, reject, serialize or replace a change made after its read.

This is a concurrency example, not a report that LACNIC has lost an update. The server may prevent exactly that outcome. The point is that the checked request and response examples do not tell the client which rule applies. They show no ETag, If-Match, revision token, base-list hash or equivalent precondition. Nor do they show a dry-run, preview or intended diff. The documented update response has no public example body or response headers from which an operation outcome could be reconciled.

The distinction is important for ROAs because a list is not a catalogue of harmless labels. Under the current ROA profile in RFC 9582, an authorization binds IP address space to an origin AS, with an optional maximum length. RFC 9319 explains why careless use of maxLength can change which more-specific announcements are covered. Creating, narrowing or omitting an authorization can change the evidence against which route-origin validation classifies announcements.

That does not make the API responsible for a router’s decision. Relying networks choose how to fetch and use RPKI data. It does mean that the registry write deserves an operating contract proportionate to its effect. An organization should not have to infer the concurrency model from whether a request happened to succeed.

Two public surfaces should come from one executable definition

The first repair is documentary. The website table, the /info destination and the Postman collection should be projections of one versioned route definition. If update is organization-scoped list replacement, the summary table should say so. If an item-addressed route remains supported, the contract should explain whether it edits one object, translates into a set operation or belongs to an older compatibility surface.

The Postman publication metadata records a publish date in June 2023, but that is not a verified last-update timestamp. The collection was fetched through its active latest version tag. What matters for an operator is not guessing which page is newer from a date; it is LACNIC publishing one authoritative version identity across every surface.

The second repair is transactional. A complete list should travel with the state identity against which it was prepared. That could be an opaque revision, an ETag, a normalized list hash or another server-issued token. The form matters less than the rule: accept this replacement only if the organization’s current list is still the base I inspected. A stale base should produce a conflict that makes no change.

The third repair is explanatory. Before commitment, a dry-run or preflight should return the intended adds, modifications and removals, including changes to prefix, origin AS and maxLength. It should distinguish an explicit removal from an entry that vanished because a client serialized an incomplete local model. Validation errors and stale-state conflicts should appear before mutation, not be reconstructed afterward.

The fourth repair is evidentiary. A successful or rejected attempt should return one atomic operation identifier, the contract version, the accepted base identity, the resulting identity and a bounded outcome. A correction should point to the operation it supersedes. The authorized organization needs that chain; the public does not need personal account names, security controls or credentials.

Contract element What it closes
Route and schema version Which public write semantics governed the request
Organization plus base list identity Which observed state the client intended to replace
Explicit add/change/remove diff What the complete payload meant to do
Dry-run or preflight Whether validation and staleness were discovered before mutation
Atomic operation and result identity Whether one complete transition was accepted, rejected or retried
Supersession pointer How a later correction preserves rather than rewrites history

This object is smaller than a new governance process. It asks the API to tell the truth about its own transition. It keeps LACNIC’s potentially efficient desired-state design, keeps the organization as the authority over its authorizations, and gives automation a proof-of-control boundary that a route table alone cannot supply.

LACNIC’s public RPKI material emphasizes the practical importance of creating correct ROAs and correcting incorrect ones. Its API can turn that operational need into repeatable automation. The remaining work is to make the automated unit unambiguous. An operator should not have to choose between believing the serial number in one table and discovering, after following the current-documentation link, that the actual public contract is the whole set.

Sources