L’API de .fr pour les Bureaux d’Enregistrement (1/4)

Notez bien que l’accès à l’API n’est pas publique, il est réservé aux bureaux d’enregistrement accrédités par l’Afnic. Le public qui souhaiterait interroger automatiquement le contenu de .fr peut utiliser le protocole RDAP (Registration Data Access Protocol)².

Qu’est-ce qu’une API ?

L’acronyme API (Application Programming Interface) désigne deux choses. Le sens traditionnel est pour désigner l’interface d’une bibliothèque logicielle, la signature des fonctions que le programmeur va utiliser, signature qu’on souhaite en général assez stable pour ne pas avoir à changer son code trop souvent. Ainsi, la documentation de la bibliothèque standard Python nous dit que la fonction str.upper ne prend comme paramètre que l’objet (une chaine de caractères) à qui elle s’applique, et qu’elle renverra une chaine de caractères (mise en majuscules). L’ensemble des types, constantes, fonctions, etc, définis dans cette documentation est l’API de la bibliothèque standard du langage Python.

Mais, de nos jours, l’acronyme API sert souvent à désigner autre chose, une interface à laquelle on accède via le réseau, en général par des requêtes utilisant le protocole HTTP. Il s’agit toujours d’un outil pour les programmeurs (le P de API) mais qui au lieu d’exécuter du code local va appeler du code qui tourne sur une machine distante. Il existe aujourd’hui d’innombrables services sur l’Internet qui ont une telle API. La plupart du temps, ces API suivent les principes REST (REpresentational State Transfer) : un URI (Uniform Resource Identifier) pour désigner un objet sur lequel on va appliquer une action, et l’utilisation des méthodes HTTP (GET, PATCH, DELETE, etc) et des codes de retour HTTP (comme le fameux 404) pour indiquer, respectivement, l’action à effectuer et son résultat. Lorsqu’il faut transmettre davantage d’informations, celles-ci sont, de nos jours, en général encodées en JSON (JavaScript Object Notation).

Les usages

On l’a vu, les API sont faites pour les programmeurs. Le but est d’automatiser des tâches, au lieu qu’un humain ne clique sur les champs d’un formulaire Web. Si vous n’avez que peu d’opérations à faire, et rarement, l’automatisation n’est sans doute pas très utile. Les API sont conçues pour les opérations en quantité, ou bien qui sont répétées souvent.

Un premier exemple d’utilisation peut être, pour un Bureau d’Enregistrement, l’ajout de fonctions à son site Web³, par exemple pour déterminer si un nom de domaine est libre ou pas. Grâce à l’API⁴, le BE peut ajouter au code du site Web des requêtes vers les serveurs du registre, qui répondront si ce nom est enregistrable ou pas.

Mais l’API peut également servir à faire des opérations en masse. Si vous gérez ne serait-ce que trente noms de domaine, ajouter un serveur de noms supplémentaire à ces trente domaines via un formulaire Web serait pénible (sans compter les risques d’erreur humaine lors de la saisie dans le formulaire). L’API simplifie tout cela, une simple boucle sur la liste des noms et tout est fait proprement. Même chose pour, par exemple, la création de noms. Si vous avez dans un fichier une liste de vingt noms à créer, avec les mêmes informations, utiliser l’API pour les créer est plus simple et plus sûr que de faire les vingt noms un par un⁵.

Pour certaines de ces opérations, on pourrait utiliser EPP, bien sûr, mais il est souvent jugé très complexe par les programmeurs et beaucoup préfèrent une API REST, avec les classiques HTTP et JSON.

L’API de .fr et sa documentation

Voyons maintenant l’API de .fr. Sa documentation complète est accessible en ligne. Le principe est que vous allez devoir faire des requêtes HTTP, à des URI commençant par https://api-sandbox.nic.fr/v1/ pour le bac à sable⁶ et par https://api.nic.fr/v1/ pour la vraie base de données. Les éventuels paramètres seront indiqués dans l’URI si l’objet existe déjà  ou dans des données JSON envoyées avec la requête HTTP. Les réponses contiendront le code de retour HTTP et éventuellement des données au format JSON. La documentation indique les paramètres, le contenu des réponses, et donne des exemples en utilisant le programme en ligne de commande curl, qui est très pratique pour essayer l’API. Voici par exemple comment s’informer sur la disponibilité d’un domaine :

curl --header ‘Content-Type: application/json’ \

    --header "Authorization: Bearer eyJhbGnQ0…" \

    --data '{"names": ["nexistepas.fr", "nic.fr"]}' \

  https://api-sandbox.nic.fr/v1/domains/check | \

 jq .

Détaillons : on indique à curl deux champs de l’en-tête HTTP, l’un donnant le type des données envoyées (JSON) et l’autre assurant l’authentification (traitée plus en détail dans la section suivante). Les données envoyées sont un objet au format JSON qui contient deux noms de domaine dont on voudrait connaître la disponibilité. Le résultat de la commande curl est passé au programme jq, qui va formater le JSON de manière plus lisible :

{

  "response": [

    {

      "name": "nexistepas.fr",

      "available": true

    },

    {

      "name": "nic.fr",

      "available": false,

      "reason": "IN_USE"

    }

  ]

}

On voit qu’un des deux noms est disponible à l’enregistrement, l’autre étant déjà réservé.

curl n’était utilisé que pour l’exemple et le déboguage, vous utiliserez probablement le langage de programmation de votre choix (c’est tout l’intérêt des API réseau). Nous verrons cela dans les articles suivants.

Authentification

Nous avons vu plus haut que l’accès à l’API n’est pas public, il nous faut donc traiter la question de l’authentification. Pour accomplir des opérations avec l’API, vous devez obtenir au préalable un jeton, ce qui se fait par un appel à l’URI https://login-sandbox.nic.fr/auth/realms/fr/protocol/openid-connect/token (pour le bac à sable) ou https://login.nic.fr/auth/realms/fr/protocol/openid-connect/token (pour la production). Vous devrez indiquer votre identificateur et votre mot de passe. Le jeton est valable pour une durée limitée. Il devra ensuite être placé dans le champ de l’en-tête HTTP Authorization. Les exemples de code donnés par la suite montrent concrètement comment faire cela.

Le code

Passons donc au code. Les articles suivants vont montrer les programmes pour les opérations suivantes :

• obtenir la liste de ses domaines⁷,
• se renseigner sur la disponibilité d’un domaine et savoir s’il peut être enregistré,
• créer un domaine,
• supprimer un domaine,
• ajouter un serveur de noms à tous ses domaines.

Trois langages de programmation seront utilisés, Python, Go et Elixir⁸. Pour des raisons de place, les articles ne montreront qu’une version simplifiée des programmes. Une version complète est disponible sur notre Gitlab.

^{1 – Elle est également disponible pour les domaines ultra-marins comme .pm.}

^{2 – Qui fera l’objet d’un prochain article !}

^{3 – Je rappelle toutefois que certaines opérations effectuées via l’API peuvent être sensibles, par exemple la suppression d’un nom de domaine, et que développer un site Web sécurisé, c’est-à-dire ne permettant pas à un tiers malveillant d’effectuer des opérations à sa guise, est une tâche délicate. Pensez donc à la sécurité et ne vous improvisez pas développeur sans connaître les bonnes pratiques de développement sécurisé.}

^{4 – Pour ce cas de la recherche de disponibilité, on ne peut pas utiliser le DNS, car un nom peut être enregistré sans être délégué dans le DNS. Et RDAP n’est pas idéal non plus, car il en fait à la fois trop (donner des informations détaillées sur un domaine) et pas assez (indiquer non seulement si un nom n’est pas enregistré, mais aussi s’il est enregistrable, par exemple s’il n’est pas un nom réservé).}

^{5 – Attention toutefois : l’automatisation peut avoir de mauvaises conséquences en cas de bogue dans le programme. Si certaines opérations comme la recherche de disponibilité sont relativement inoffensives, celles qui modifient la base de données du .fr sont plus sensibles. Une boucle maladroite qui créerait des noms en quantité, noms qui vous seront facturés, est un exemple. Une boucle qui supprimerait ou modifierait des noms de domaine en est un autre. N’hésitez donc pas à utiliser le bac à sable (comme dans les exemples de code qui suivent) pour tester.}

^{6 – Environnement de test, qui n’utilise pas de données réelles et qui n’est pas facturé.}

^{7 – C’est un exemple d’une opération qui ne peut pas se faire en EPP.}

^{8 – Une version en Rust existe également dans le dépôt mais ne fait pas l’objet d’un article.}