Résumé

  • Dans la spécification OpenAPI actuelle d’APNIC, les requêtes de lot distinguent create, update et delete, tandis qu’un élément de résultat ne déclare que status et message.
  • Le contrôle utile est modeste : un indice ou une clé opaque, la famille d’opération, un code d’issue et, si possible, une référence sûre vers la ressource concernée.

Un opérateur n’a pas besoin d’une panne pour rencontrer une incertitude. Il suffit d’un lot parfaitement banal : deux objets de route à créer, un troisième à modifier, un quatrième à supprimer. L’API valide la requête, renvoie l’adresse d’une tâche asynchrone, puis traite le travail. Plus tard, la tâche contient plusieurs résultats.

Le document public d’APNIC précise le vocabulaire de ces résultats. Le champ status peut valoir success, failure ou notification; un message peut l’accompagner. Mais l’élément ne comporte ni nom du tableau d’origine, ni position dans la requête, ni clé fournie par le client, ni identifiant de ressource, ni location. Le texte annonce une entrée distincte pour chaque action, sans établir de règle selon laquelle l’ordre des réponses reproduirait celui des demandes.

Ce constat porte sur un fichier, pas sur un incident. L’OpenAPI examinée est la version 0.0.2, au format 3.0.0, longue de 59 622 octets et 1 934 lignes. Aucun lot authentifié n’a été envoyé. Rien ne prouve que le service en production réordonne les réponses, confonde deux actions ou oblige réellement un membre à deviner. APNIC peut très bien maintenir un ordre stable, inclure la cible dans le message et conserver une corrélation exacte dans ses journaux.

La limite est plus étroite : cette garantie ne figure pas dans le contrat machine consulté.

La meilleure défense d’APNIC vient d’abord

L’architecture publiée contient déjà plusieurs bonnes décisions. Les écritures POST, PUT et DELETE sont prises en charge par des objets de tâche. La requête est d’abord validée; le client reçoit ensuite un lien qu’il peut interroger. Une tâche peut conserver le contenu initial et, lorsqu’elle est terminée, présenter l’heure de traitement, le code HTTP et le corps de réponse.

Le résultat de lot n’est pas non plus réduit à un oui ou un non global. APNIC prévoit des lignes distinctes pour les actions et les notifications. Le préambule indique que les lots prennent effet de manière transactionnelle lorsque c’est possible et que, de façon générale, les interactions qui n’affectent pas le Whois sont traitées transactionnellement. Les opérations de lecture et les vues MyAPNIC offrent en outre des moyens de rapprochement.

Il existe aussi un contexte d’ouverture. APNIC a présenté un environnement de test avant le lancement, organisé un hackathon, montré le produit à APNIC 58 et publié deux adresses de retour, l’une privée et l’autre publique. Une équipe cliente peut donc vérifier son intégration et demander des précisions.

Le choix d’un schéma compact peut être volontaire. Une convention d’ordre peut être appliquée sans exception dans le code. Les messages peuvent être suffisamment explicites pour l’usage courant. Les transactions peuvent réduire le nombre d’états intermédiaires. Et des tests internes peuvent protéger des garanties qu’APNIC ne souhaite pas détailler publiquement.

Ces hypothèses favorables sont importantes. L’article ne dit pas qu’une action a été perdue, répétée ou appliquée au mauvais objet. Il ne dit pas qu’un membre a subi un dommage. Il ne demande ni journaux privés, ni topologie de base de données, ni données de registre. Il demande seulement qu’une relation indispensable à l’automatisation soit rendue explicite.

La requête possède une adresse; la réponse n’en possède pas

Les schémas de requête sont structurés avec soin. Pour le DNS inverse, les routes et les ASPA, un lot répartit les actions entre create, update et delete. La forme de chaque élément dépend du type d’objet et de l’opération. Une suppression de route peut viser un identifiant. Une suppression RDNS vise une plage. Une modification ASPA peut associer identifiant, ASN client et liste d’ASN fournisseurs.

Cette structure donne naturellement une adresse à chaque action : famille de ressource, type d’opération, position dans le tableau. Le client sait qu’il a envoyé, par exemple, l’élément 1 de delete.

Le schéma commun de réponse efface cette adresse. Sous results, l’objet interne ne déclare que deux propriétés. status décrit l’issue générale; message reste une chaîne sans grammaire machine définie. Aucun champ ne dit « ceci répond à delete[1] ».

Peut-être que la position suffit en pratique. Mais l’ordre n’est un contrôle que lorsqu’il est spécifié. Faut-il concaténer create, puis update, puis delete? Les notifications prennent-elles une position? Une validation refusée produit-elle une ligne? Une transaction annulée renvoie-t-elle une ligne par action ou un résultat de groupe? Le document examiné ne tranche pas ces questions.

Le standard OpenAPI ajoute une seconde nuance. Dans un schéma d’objet, une propriété mentionnée n’est pas automatiquement obligatoire. Elle le devient lorsqu’elle figure dans un tableau required. Or batch-response ne comporte pas ce tableau au niveau supérieur. Le document autorise donc type et results, mais ne les impose pas comme forme minimale. Les schémas task, task-link et success-response présentent la même caractéristique.

Encore une fois, cela ne signifie pas que le serveur omet ces champs. Cela signifie qu’un générateur de client ou un test de contrat ne peut pas tirer la garantie du fichier seul.

Une hypothèse d’ordre devient une dette

Prenons un scénario de laboratoire, pas une observation d’APNIC. Un lot contient trois créations et deux suppressions. La réponse fournit successivement success, failure, success, success, notification. Si le client ne dispose d’aucune règle publiée, plusieurs lectures restent possibles. La notification peut être une ligne indépendante. L’échec peut viser la deuxième création, la première suppression ou l’ensemble transactionnel. Le message peut lever le doute pour une personne, sans offrir une clé stable à un programme.

L’automatisation finit alors par fabriquer son propre contrat. Une équipe suppose un ordre. Une autre analyse le texte. Une troisième découpe chaque lot en appels unitaires. Une quatrième relit toutes les ressources après écriture.

Ces solutions ont un coût différent. L’appel unitaire réduit l’ambiguïté, mais abandonne l’efficacité et parfois l’intérêt transactionnel du lot. Le rapprochement intégral ajoute des lectures, de la latence et de la pression sur les limites de débit. L’analyse du message fonctionne jusqu’à ce que sa formulation évolue. L’ordre implicite fonctionne jusqu’à l’ajout d’une notification ou d’un nouveau type d’action.

La charge n’est pas répartie équitablement. Un grand opérateur peut maintenir un adaptateur, des jeux d’essai et des alertes. Une petite équipe reprend souvent un exemple et ne découvre l’hypothèse qu’au moment d’un échec. Les mainteneurs de bibliothèques deviennent alors les dépositaires officieux d’une sémantique que le contrat officiel pourrait exprimer en quelques octets.

Une carte de résultats, pas un journal de transactions

Le remède minimal consiste à donner une adresse à chaque résultat. APNIC pourrait renvoyer le nom du tableau et l’indice de l’élément : create[0], update[2], delete[1]. Une solution plus robuste autoriserait le client à fournir une clé opaque pour chaque action, puis la renverrait à l’identique. Cette clé n’a pas besoin de révéler l’objet; elle peut n’avoir de sens que dans le travail du membre.

À côté de cette corrélation, une ligne peut indiquer la famille d’opération et un code d’issue stable. Lorsqu’il est sûr de le faire, le serveur peut joindre l’identifiant de la ressource ou une location. Un objet de problème structuré peut expliquer l’échec sans faire du texte libre la clé de rapprochement. Une instruction bornée—corriger, interroger la tâche, vérifier l’état ou renvoyer—réduit les répétitions inutiles.

Si plusieurs actions partagent une transaction, l’appartenance et l’issue peuvent être décrites au niveau du groupe. Il ne faut pas inventer cinq validations indépendantes lorsqu’un seul ensemble est atomique. Il suffit que le client sache quelles actions sont couvertes par la même décision.

Une règle d’ordre normative, accompagnée d’exemples mêlant créations, modifications, suppressions et notifications, serait déjà un progrès. La clé opaque résiste mieux aux réponses partielles et aux évolutions futures. Le choix technique appartient à APNIC; l’exigence de fond est simplement que le lien soit déclaré et testable.

Le schéma fait partie du service

L’API de registre a été lancée pour permettre aux membres d’automatiser des opérations auparavant effectuées dans MyAPNIC. À partir du moment où APNIC encourage cette dépendance, le fichier OpenAPI devient une surface opérationnelle. Il alimente des clients générés, des tests et des procédures de reprise.

Le document actuel a le mérite d’indiquer clairement l’asynchronisme, les limites de débit, la qualification transactionnelle et les voies de retour. Le champ manquant ne traduit donc pas un produit vide. Il révèle une couture typique d’un service assez utile pour devenir une infrastructure logicielle chez ses utilisateurs.

Il n’est pas nécessaire d’attendre qu’un mauvais renvoi soit prouvé. Chaque résultat doit seulement pouvoir désigner la question à laquelle il répond. Alors success, failure et notification deviennent des états actionnables, et non des étiquettes que l’opérateur replace à la main.

Sources