Summary

  • APNIC’s current OpenAPI document models RDNS, route and ASPA batch requests as create, update and delete arrays, but a batch result item declares only status and message.
  • The proportionate remedy is not a transaction dump. It is an explicit, versioned join—an item index or opaque client key, operation class, outcome code and safe resource reference—between every submitted action and its returned result.

Imagine a perfectly ordinary automation job. It asks to create two route objects, update a third and delete a fourth. APNIC validates the submission, returns a task link and processes the work asynchronously. When the client polls later, the task contains a batch response. The response has four result rows.

The public contract tells the client what may appear inside each row: a status chosen from success, failure or notification, and a string called message. It does not give the row a request-array name, an item index, an echoed client token, a resource ID or a location. Nor does the checked OpenAPI document say that the first result answers the first create, that updates follow creates, or that notifications are interleaved according to a defined rule.

That hypothetical is not an account of APNIC’s running service. No authenticated batch was submitted for this review. No member has reported a mismatch here. The runtime may preserve order consistently; the message may name the target; internal logs may carry an exact join. The evidence is narrower: version 0.0.2 of the public OpenAPI 3.0.0 document does not declare that join.

Begin with the strongest defence

APNIC has built more accountability into the interface than a bare fire-and-forget endpoint would provide. All POST, PUT and DELETE submissions are described as asynchronous tasks. The task can retain the original request, record when it was submitted, and later carry a response with a processing time, HTTP status code and content. A client can preserve the task URL and inspect the original payload beside the outcome.

The batch response is also not a single undifferentiated Boolean. APNIC says it contains separate result entries for each action, plus notifications where relevant. That is a useful design decision. The introductory documentation says batches take effect transactionally where possible and says, in general, interactions other than those affecting Whois are handled transactionally. APNIC exposes GET and list operations, maps API functionality to MyAPNIC, offers a testbed history and publishes both private and public feedback addresses.

Those features may make practical reconciliation straightforward. A generated client might rely on a stable ordering convention documented elsewhere. Messages might contain enough object detail for a human operator. A transaction may ensure that every action in a particular family shares one outcome. APNIC may test all of this continuously without exposing member data or internal database boundaries.

A serious critique has to preserve those possibilities. The article is not a finding that APNIC reorders results, applies the wrong action, partially commits a batch or causes unsafe retries. It is not a demand to publish credentials, registry contents or transaction logs. It asks only what an independent integrator can rely on from the published machine contract.

The request is typed more precisely than the response

The asymmetry becomes visible when the schemas are read side by side. RDNS, route and ASPA batch requests separate actions into named arrays: create, update and delete. The item shape depends on both the resource family and the operation. A route deletion can carry an existing ID. An RDNS deletion identifies a range. An ASPA update can carry an ID, customer ASN and provider ASN set.

On the response side, the common batch-response schema has a results array. Within each result item, the exact declared property set is just status and message. The status vocabulary distinguishes success, failure and notification. It does not distinguish the request array or identify the request position. The string is not assigned a machine-readable grammar in the schema.

That does not make the response wrong. It makes the join implicit. The request says, in structure, “this is create item 0” and “this is delete item 1”. The response does not say, in structure, “I answer delete item 1”. If an ordering convention supplies the missing relation, the convention is part of the API’s behaviour and belongs in the contract.

OpenAPI makes the boundary sharper. Under OpenAPI 3.0, object properties are not required merely because they are listed; they are required when named in a required array. The checked batch-response schema declares no such array. Its type and results properties therefore describe permitted shape, not a minimum response guarantee in this document. The task, task-link and success-response schemas also lack top-level required arrays.

This is a schema observation, not a runtime observation. APNIC may always return every field. The point is that a client generator or contract test cannot infer that guarantee from this document alone.

Order is a control only when order is specified

Suppose, purely as a test case, that a route batch submits three creates and two deletes. The returned rows are success, failure, success, success, notification. There are several plausible interpretations unless the relationship is explicit. Results might follow the concatenated request-array order. Notifications might occupy their own rows. A failure message might name an object. A transactional batch might make one failure describe more than one submitted item.

None of those interpretations is alleged to be APNIC’s implementation. Their coexistence is precisely why a public ordering rule or correlation key matters. Automation should not have to learn semantics by provoking errors in a production registry. It should not have to parse a sentence whose wording was designed for an operator rather than a program. It should not assume that the absence of a result row means success, rollback, suppression or a changed response version.

An explicit join also narrows retries. If a client knows that result delete:1 failed validation while create:0 succeeded, it can inspect the failed target and avoid repeating the successful one. If the batch is atomic, the result can say that the transaction group rolled back without inventing five unrelated outcomes. If the client should poll rather than resubmit, that direction can attach to the item or group that requires it.

The benefit is not maximal telemetry. It is decision containment. A small identifier prevents the operator from widening a local uncertainty into a whole-batch retry.

Asynchrony preserves the question rather than answering it

The task wrapper is useful because processing continues after the initial HTTP exchange. RFC 9110 makes the generic boundary clear: a 202 Accepted response means a request has been accepted for processing, not that processing has finished successfully. APNIC goes further by returning a task that can later hold the response.

Yet the task joins a request to a response at batch level. It does not, in the checked schema, add a join between each request item and each result item. Retaining the original request lets a human compare two arrays. It does not tell a generated client which comparison rule is authoritative.

RFC 7240’s respond-async preference and Google’s AIP-151 are useful comparative designs for long-running work, not rules that APNIC has violated. RFC 9457 offers structured problem details, but it also does not prescribe APNIC’s batch mapping. These sources matter as design vocabulary. The governing evidence remains APNIC’s own schema.

The cost falls unevenly

A member with one hand-written request may never notice the omission. A person can read the message, open MyAPNIC and infer the intended object. A software team operating hundreds of changes has a different problem. It must encode an assumption, add a message parser, split batches into single-item calls or perform broader read-after-write reconciliation.

Each workaround transfers contract work to the client. An undocumented order assumption is cheap until a new response version inserts a notification. Message parsing is cheap until wording changes. Single-item batches reduce ambiguity but surrender the throughput and transaction advantages of batching. Broad reconciliation can be safe, but it adds API calls, rate-limit pressure and operational delay.

That distribution matters for governance. Large operators can build defensive adapters and test suites. Smaller members may copy an example and carry the hidden assumption for years. Consultants and open-source maintainers then become unofficial custodians of semantics that the authoritative contract could express in a few fields.

A thin batch-result map

The smallest durable remedy is a result map, not a forensic ledger. Each accepted action could receive either a server-defined tuple such as request array plus zero-based index, or an opaque client-supplied item key that the server echoes. The latter need not reveal anything about the resource; it can be meaningful only inside the submitting member’s job.

Beside that join, the row needs an operation family and a stable machine outcome code. A safe resource ID or location can be returned where the operation creates or updates an object. A structured problem object can describe failure without turning free-form message text into the primary key. Retry direction can say whether the client should correct, poll, reconcile or resubmit. A schema or test version makes later change visible.

Transaction scope can remain a group property. If five result rows belong to one atomic unit, a group ID and group outcome are clearer than pretending each item committed independently. Sensitive details can stay private. The public contract needs the relation, not the database transaction log.

There is an even smaller alternative: specify the ordering rule normatively and provide examples for mixed create, update, delete and notification responses. That would be better than silence. An echoed client key is stronger because it survives filtering, sparse results and future reordering, but the first decision is simply to make one rule explicit and testable.

A specification is part of the operating surface

APNIC launched the Registry API to let members automate work previously performed through MyAPNIC. Its preview, hackathon and product demonstrations show an institution encouraging software to depend on the interface. That makes the schema more than documentation around the service. It is the boundary from which clients generate code, tests and operational expectations.

The current document is admirably compact and candid about rate limits, asynchronous tasks, transaction qualifications and feedback routes. The missing request-item field is therefore not evidence of indifference. It is the kind of seam that becomes visible only after an API succeeds well enough to attract durable automation.

APNIC does not need to prove a failure to improve that seam. It needs to give every result row an address back into the request. Once the join is explicit, success, failure and notification become outcomes a machine can act on rather than labels a human must place by inference.

Sources