Nouvelle API publique de Gandi (v5) : présentation, documentation

Le notaire du web et hébergeur français a lancé son interface Gandi version 5, avec une architecture où chaque produit est géré par une API REST spécifique. Quelques explications.

Gandi V5 API publique

La refonte du site Gandi.net en V5 était donc bien plus qu’un coup de peinture, introduisant un changement conséquent de l’architecture des services, grâce à une nouvelle API HTTP qui utilise les verbes HTTP et JSON comme format de données.

Tous les détails se trouvent dans cet article de blog très complet sur le sujet.

Sur l’API publique de Gandi

Sur la précédente version du site, toutes les opérations du site passaient par une API XML/RPC. Avec Gandi version 5 a été développée une architecture où chaque produit est géré par une API REST spécifique.

Par exemple, une API se charge exclusivement du DNS, une autre des domaines, et encore une pour les produits d’hébergement. Ce modèle connu sous le nom « micro services » fonctionne bien et permet à chaque produit d’avancer à son rythme et d’être cloisonné.

L’entreprise publie un schéma simplifié de l’architecture, avec des APIs qui communiquent avec des services asynchrones ou une ou plusieurs bases de données.

Format de documentation sur l’API

Pour Gandi, il fallu choisir un format assez tôt dans le projet, ce fut RAML. Il s’agit d’une spécification de description d’une API HTTP en utilisant des fichiers au format YAML. Voici un extrait (réel) de la documentation d’une partie de l’API mailbox :

yaml
/forwards :
   /domain :
     displayName : Manage your forwarding addresses
     description : |
      Forwarding addresses make it possible to redirect mail from 
      one or more of your domain’s email addresses to an external 
      address. Learn more on the documentation.
securedBy : [lib.api-key]

is : [lib.restricted]
uriParameters :

  domain :

   type : lib.Domain

   description : Domain name.
get :

  displayName : List forwarding addresses

  description : |

    This route returns a paginated list of forwarded email addresses

    on the given domain.
is : [lib.paginated]
queryString :

  type : lib.email.ForwardListFilters
responses :

  200 :

   body :

    application/json :

     type : lib.email.ForwardList

Feuille de route

"Dans les mois à venir, nous allons progressivement ajouter des services et fonctionnalités manquantes à l’API publique", indique l’entreprise sur son blog. "Concernant l’actuelle API XML/RPC, nous n’allons pas la fermer immédiatement, vous laissant le temps de migrer vos outils vers la nouvelle API, à votre rythme."