Resumen

  • Las solicitudes por lote de RDNS, rutas y ASPA separan create, update y delete; el elemento común de respuesta solo declara status y message.
  • Un mapa mínimo—índice o clave opaca, tipo de operación, código de resultado y referencia segura al recurso—permitiría reconciliar cada acción sin exponer datos del miembro.

El caso difícil no requiere una caída. Puede ocurrir en una mañana tranquila, cuando un operador envía un lote con dos rutas nuevas, una modificación y una baja. La API acepta el cuerpo, entrega un enlace a una tarea y procesa la solicitud de forma asíncrona. Cuando el cliente consulta la tarea, recibe varias filas de resultado.

Según el OpenAPI público de APNIC, cada fila puede tener un estado success, failure o notification y una cadena message. Hasta ahí hay información útil. Falta, sin embargo, una coordenada: la fila no declara si responde a create[0], a update[0] o a delete[0]. Tampoco incorpora una clave del cliente, un identificador de recurso, una ubicación ni una regla de orden.

Esta observación está limitada al documento público actual. La copia examinada tiene 59.622 bytes, 1.934 líneas, versión de API 0.0.2 y formato OpenAPI 3.0.0. No se ejecutó ninguna escritura autenticada. No hay evidencia de que el servicio en funcionamiento altere el orden, confunda acciones o haya causado un reintento incorrecto.

APNIC podría mantener una correspondencia perfecta en producción. El texto del mensaje podría nombrar el objeto. Sus registros internos podrían unir cada entrada y salida. El límite verificable es otro: ese enlace no está expresado como propiedad ni como regla normativa en el contrato revisado.

La defensa más sólida

El diseño tiene controles valiosos. APNIC no trata las escrituras como mensajes enviados al vacío. Los POST, PUT y DELETE se gestionan mediante tareas asíncronas. Tras validar el esquema, el servidor entrega un enlace consultable. La tarea puede conservar la petición original y más tarde incluir el momento de procesamiento, el código HTTP y el contenido de la respuesta.

El lote tampoco termina en un único indicador global. La documentación dice que batch-response contiene entradas separadas para cada acción, además de notificaciones cuando sean pertinentes. La introducción añade que los lotes surten efecto de forma transaccional cuando es posible y que, en general, las interacciones que no afectan a Whois se manejan transaccionalmente.

El cliente dispone además de lecturas, listados y MyAPNIC para comprobar el estado. APNIC presentó un entorno de pruebas, invitó a experimentar en un hackatón, mostró el producto en APNIC 58 y mantiene canales de comentarios públicos y privados. Es razonable pensar que una integración diligente pueda resolver la mayoría de los casos.

También es posible que exista una convención de orden estable, aunque no figure en el archivo. Los mensajes quizá estén redactados para identificar de manera inequívoca el recurso. Las pruebas internas pueden ser mucho más estrictas que el esquema público. Un contrato compacto reduce carga de mantenimiento y deja espacio para información humana.

Por eso no corresponde convertir una ausencia documental en un incidente. Este análisis no afirma que APNIC pierda, duplique, reordene o aplique mal ninguna acción. No atribuye daño a un miembro. No exige revelar credenciales, objetos privados, topología o transacciones internas. Pide que una relación necesaria para automatizar deje de depender de una suposición.

Dos lados con distinta precisión

El lado de la solicitud está bien tipado. Para RDNS, rutas y ASPA, los lotes organizan las acciones en matrices distintas: create, update y delete. La forma cambia según el recurso y el verbo. Una baja de ruta puede usar un ID; una baja RDNS señala un rango; una modificación ASPA puede llevar ID, ASN del cliente y ASN de proveedores.

Cada acción, por tanto, ya tiene una dirección natural dentro del cuerpo: familia, operación e índice. La aplicación sabe que envió delete[1] aunque el contenido del objeto sea sensible.

Al pasar a la respuesta común, esa dirección desaparece. El objeto interior de results declara exactamente dos propiedades. status clasifica el resultado; message es una cadena sin estructura de correlación especificada. No hay un campo que diga a qué dirección de la solicitud contesta.

Una lista ordenada podría bastar, pero solo si el orden forma parte del contrato. ¿Se concatenan primero las altas, luego los cambios y después las bajas? ¿Las notificaciones ocupan una posición propia? ¿Una acción descartada durante validación genera fila? ¿Un resultado transaccional resume varias acciones? El documento consultado no responde.

OpenAPI introduce otra diferencia entre lo habitual y lo exigible. En un objeto, mencionar una propiedad no la vuelve obligatoria; debe aparecer en required. El esquema superior de batch-response no incluye esa lista. Por tanto, el archivo describe type y results, pero no fija ambos como contenido mínimo. Lo mismo ocurre en los niveles superiores de task, task-link y success-response.

Puede que APNIC siempre devuelva todos esos campos. La conclusión no es que falten en ejecución. Es que una herramienta generada desde el contrato no puede exigirlos basándose solo en ese contrato.

El orden implícito se convierte en software permanente

Considérese una prueba hipotética con tres altas y dos bajas. Las cinco filas regresan como success, failure, success, success, notification. Sin una regla publicada, el cliente debe elegir una teoría. Puede asumir una concatenación de matrices, buscar el nombre del objeto en el mensaje o releer el registro entero.

Cada teoría funciona hasta que deja de hacerlo. Una notificación nueva puede desplazar posiciones. Un cambio editorial puede romper el analizador de mensajes. Dividir el lote en solicitudes unitarias sacrifica rendimiento y quizá la ventaja transaccional. La reconciliación amplia añade latencia, peticiones y consumo de cuota.

El riesgo no es solo técnico. Las organizaciones grandes pueden sostener adaptadores y bancos de pruebas. Los miembros con menos capacidad tienden a copiar el ejemplo disponible y a heredar su supuesto invisible. Un proveedor de software o un mantenedor de código abierto termina definiendo de facto cómo se interpreta la API.

El contrato oficial puede evitar esa privatización de la semántica. Un campo de pocos bytes traslada una regla desde docenas de implementaciones particulares hacia una fuente verificable.

El mapa mínimo de resultados

La opción más sencilla es devolver, en cada fila, la matriz y el índice de origen: create:0, update:2, delete:1. Una variante más resistente permite que el cliente asigne una clave opaca a cada acción y exige que el servidor la refleje. La clave no revela prefijos, ASN ni contactos; solo vincula dos partes de una conversación autorizada.

La fila puede añadir el tipo de operación y un código de resultado estable. Cuando proceda, un ID o location seguro facilita la lectura posterior. Un objeto de problema estructurado explica un rechazo sin convertir la prosa libre en clave primaria. Una instrucción concreta distingue corregir, consultar, reconciliar o reenviar.

Si varias acciones pertenecen a una unidad atómica, la respuesta puede identificar el grupo y su resultado. No hace falta publicar el registro de la transacción. Basta con evitar que cinco filas parezcan cinco confirmaciones independientes cuando en realidad comparten una decisión.

Existe una solución aún más ligera: declarar de forma normativa el orden y mostrar ejemplos mixtos con altas, cambios, bajas, fallos y notificaciones. Esa solución es mejor que el silencio, aunque una clave reflejada tolera mejor respuestas dispersas y futuras ampliaciones.

El contrato es parte de la infraestructura

APNIC creó esta API para que los miembros automatizaran funciones disponibles en MyAPNIC. El historial de pruebas, lanzamiento y demostraciones muestra que espera integraciones duraderas. En ese contexto, el OpenAPI no es una nota auxiliar: alimenta SDK, tipos, validadores, pruebas y procedimientos operativos.

El archivo actual ofrece información poco común y útil sobre asincronía, límites de tasa, alcance transaccional y canales de comentarios. Precisamente por eso la ausencia de correlación merece una corrección pequeña, no una condena grande.

Cuando cada resultado pueda señalar su elemento de origen, success, failure y notification dejarán de ser fichas que una persona recoloca por intuición. Serán respuestas con domicilio propio.

Fuentes