REST API – Manuel

Dans cet article, vous apprendrez :

• Comment fonctionne WEDOS REST API
• Quels sont les endpoints disponibles
• Comment gérer les clients API
• Comment fonctionne la journalisation des requêtes API
• Questions fréquentes

---

Caractéristiques de WEDOS REST API

HTTP REST API v2 vous permet de gérer vos services WEDOS depuis vos propres applications et scripts. Toute la communication passe par HTTPS à l’adresse https://api.wedos.com, les données sont envoyées et renvoyées au format JSON.

Pour obtenir l’accès à l’API, vous devez créer un client API disposant de droits d’accès (lecture et écriture, ou lecture seule – voir le chapitre Gestion des clients ) vers un ou plusieurs endpoints (voir Endpoints). Chaque requête est journalisée (voir Journalisation des requêtes).

Limite de requêtes

• La limite par défaut est de 1 000 requêtes par heure et par client API. Chaque client a sa propre limite, partagée entre toutes les API (domains, wdns, wgp, …).
• Toutes les requêtes sont comptabilisées dans la limite, y compris celles qui sont refusées.
• La limite actuelle est indiquée dans la liste des clients de l’administration.
• Si la limite ne vous suffit pas, contactez le support client via le formulaire ⧉. Indiquez la limite souhaitée et la raison pour laquelle vous voulez la définir. Nous pouvons l’augmenter individuellement pour votre compte.

HTTP REST API vs. WAPI

WEDOS propose deux API : l’ancienne WAPI et la plus récente HTTP REST API v2. Vous pouvez les comparer à l’aide du tableau suivant :

	WAPI	HTTP REST API v2
Authentification	Un seul identifiant et mot de passe WAPI pour tout le compte	Un client API distinct, avec son propre token, pour chaque application ou personne
Restrictions d’accès	Une liste obligatoire d’adresses IP pour tout le compte	Scopes d’autorisation, « Lecture seule », adresses IP et validité du token, définis pour chaque client séparément
Format	XML ou JSON, un seul endpoint, commandes dans le corps de la requête	REST (méthodes HTTP et URL), JSON
Couverture	Un large éventail de commandes pour les services WEDOS	domaines, contacts, NSSET, WEDOS DNS, WEDOS Global Protection
Log	Un seul log pour tout le compte	Un log qui identifie le client API

Nous recommandons d’utiliser :

• HTTP REST API v2 pour les nouvelles intégrations, lorsqu’elle couvre les opérations dont vous avez besoin, et partout où vous devez séparer les accès de différentes personnes ou systèmes, les limiter à la lecture seule ou retracer qui a fait quoi (audit, DORA).
• WAPI pour les opérations que HTTP REST API v2 ne propose pas encore.

Si vous souhaitez passer de WAPI à WEDOS REST API, procédez comme suit :

1. Dans l’administration, créez pour chaque application ou système un client API disposant des scopes d’autorisation nécessaires. Vous trouverez la marche à suivre au chapitre Gestion des clients .
2. Remplacez vos appels de commandes WAPI par les endpoints correspondants de la documentation de chaque API. Voir le chapitre Endpoints .
3. Les codes de résultat des opérations (par exemple 1000 OK, 3201 le domaine est déjà enregistré) sont les mêmes que dans WAPI, car HTTP REST API v2 effectue les mêmes opérations. Il existe en outre des codes généraux de la couche REST (par exemple 2000 token manquant ou invalide, 2012 client en lecture seule), décrits dans la documentation de chaque API.
4. Pendant la transition, vous pouvez utiliser les deux API en parallèle.

---

Endpoints

WEDOS REST API permet d’automatiser la gestion des domaines suivants :

• Domaines : Les endpoints /domains/ assurent l’enregistrement, les transferts et les renouvellements de domaines. Ils savent également envoyer les AUTH-ID, configurer les serveurs DNS/NSSET et le KEYSET pour DNSSEC. Leur scope d’autorisation est domaines. Vous trouverez plus d’informations dans l’article REST API – Domaines .
• Contacts de domaine : Les endpoints /contacts/ créent et gèrent les contacts de domaine. Les transferts sont disponibles pour les domaines .cz. Leur scope d’autorisation est domaines. Vous trouverez plus d’informations dans l’article REST API – Contacts de domaine .
• NSSET : Les endpoints /nssets/ créent et gèrent les objets NSSET de CZ.NIC. Leur scope d’autorisation est domaines. Vous trouverez plus d’informations dans l’article REST API – NSSET de domaine .
• DNS : L’endpoint /dns/ crée et gère les domaines DNS ainsi que les enregistrements individuels. Cela inclut les imports vers le DNS primaire et l’AXFR pour le DNS secondaire. Son scope d’autorisation est dns. Vous trouverez plus d’informations dans l’article REST API – DNS .
• WEDOS.protection : L’endpoint /wgp/ endpoints créent et gèrent les services WEDOS.protection. Leur scope d’autorisation est wgp. Vous trouverez plus d’informations dans les articles REST API – WGP Domains, REST API – WGP Services et REST API – WGP Members.

---

Gestion des clients

Vous configurez l’accès à l’API dans l’administration client, dans la section HTTP REST API . Créez un client API distinct pour chaque application, système ou personne. Pour chaque client, vous définissez :

• Scopes d’autorisation : à quelles API le client a accès,
• Lecture seule : le client peut uniquement consulter les informations (voir ci-dessous),
• Filtrage des adresses IP : adresses IP autorisées ou bloquées depuis lesquelles le client peut appeler l’API,
• Validité du token : à partir de quand l’access token est valide et quand il expire.

Le client s’authentifie avec un access token dans l’en-tête Authorization: Bearer <TOKEN> . Vous pouvez générer le token directement dans l’administration, ou votre application peut le demander elle-même à l’aide du client ID et du client secret (voir le chapitre OAuth2 ).

Création d’un nouveau client

Un nouveau client ne peut être créé que dans l’administration client. Procédez comme suit :

1. Connectez-vous à l’administration client.
2. Accédez à l’interface WEDOS REST API (actuellement indisponible).
3. Cliquez sur le bouton Nouveau client .
4. Saisissez un Nom du client (un nom court qui identifie le client dans la liste) et choisissez une ou plusieurs zones d’autorisations dans le menu Sélectionner les autorisations . Les zones disponibles correspondent aux endpoints.
5. Effectuez éventuellement d’autres réglages :
   • Cochez l’accès Lecture seule . Le client ne peut alors que demander des informations. Les requêtes qui ajoutent, modifient ou suppriment des éléments sont bloquées.
   • Dans la section Validité du token, choisissez pendant combien de temps le token reste valide après son émission : Sans expiration, 7 jours, 30 jours, 90 jours, 1 an ou Personnalisé. Les champs Valide à partir du et Expiration affichent les dates obtenues.
   • Dans la section Restrictions de sécurité, vous pouvez éventuellement activer Filtrage des adresses IP et saisir une adresse IP autorisée. Pour d’autres adresses, cliquez sur + Ajouter une autre , ou sur × pour en supprimer une. Lorsque le filtrage est activé, l’API n’accepte les requêtes que depuis les adresses indiquées.

Une fois la configuration terminée, confirmez-la avec le bouton Créer le client .

Le nouveau client apparaît dans la liste avec son nom, ses autorisations, son type d’accès (par exemple read, write), ses dates de validité et son statut. Vous pouvez filtrer la liste selon ces éléments : Autorisations, Statut, Validité et Accès.

Client Secret

Juste après la création d’un client, une boîte de dialogue Clé secrète du client s’affiche avec le message Copiez la clé secrète et conservez-la en lieu sûr.

1. Cliquez sur Copier à côté de la clé secrète.
2. Conservez la clé secrète en lieu sûr, par exemple dans un gestionnaire de mots de passe ou dans le coffre à secrets de votre serveur.
3. Cliquez sur J’ai compris, fermer.

La clé secrète n’est affichée que dans cette boîte de dialogue, enregistrez-la donc avant de la fermer. Vous en avez besoin, avec le client ID, pour demander des tokens via l’API (voir le chapitre OAuth2).

Gestion d’un client existant

Pour ouvrir la page Configuration HTTP REST API d’un client, cliquez sur l’icône de modification à côté de son nom dans la liste. Vous pouvez modifier tous les paramètres saisis lors de la création, y compris le nom et les autorisations.

Le Client ID et le Client Secret ne peuvent pas être modifiés.

Lors de la gestion d’un client existant, les commandes suivantes sont disponibles :

• Enregistrer les modifications: enregistre les modifications des paramètres du client.
• Désactiver : Désactive (bloque) le client sans le supprimer.
• Supprimer : Supprime définitivement le client.
• Retour à la liste HTTP REST API : Retour à la liste des clients.
• Actualiser : Recharge la page.

Bearer token du client

Le Bearer token sert à identifier le client lors de l’accès aux endpoints. Le champ affiche l’access token actuel du client. Cliquez sur Copier pour le copier.

Pour remplacer le token, cliquez sur Nouveau token. L’ancien token cesse immédiatement de fonctionner, mettez donc à jour toutes les applications qui l’utilisent.

La section Exemple (curl) affiche une requête prête à l’emploi avec le token actuel, à des fins de test.

OAuth2

Votre application peut demander son propre token à POST https://api.wedos.com/oauth2/token à l’aide du client ID et de la clé secrète. Toute autre méthode HTTP renvoie une erreur.

• Client ID : Dans l’ interface de gestion des clients, cliquez sur Afficher le Client ID pour afficher le client ID, puis cliquez sur Copier.
• Client Secret : La clé secrète n’est disponible qu’après la création du compte. Vous trouverez plus d’informations au chapitre Client Secret .

Utilisez l’une des deux méthodes :

• HTTP Basic (recommandé) : l’en-tête Authorization: Basic <base64(client_id:client_secret)>. curl le construit pour vous avec -u 'client_id:client_secret'.
• Dans le corps de la requête : les paramètres client_id et client_secret.

Envoyez les paramètres dans le corps au format application/x-www-form-urlencoded, ou en JSON avec l’en-tête Content-Type: application/json.

Paramètre	Obligatoire	Description
grant_type	Oui	Toujours client_credentials
scope	Non	Scopes d’autorisation séparés par des espaces, parmi domains (inclut les contacts de domaine et NSSET), wdns et wgp. Doit être un sous-ensemble des scopes du client. En cas d’omission, le token reçoit tous les scopes du client.
client_id, client_secret	Uniquement sans HTTP Basic	Identifiants du client

Exemple : HTTP Basic (recommandé)

curl -X POST -u '<CLIENT_ID>:<CLIENT_SECRET>' \
  -d 'grant_type=client_credentials' \
  -d 'scope=domains' \
  'https://api.wedos.com/oauth2/token'

Exemple : Identifiants dans le corps de la requête

curl -X POST \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<CLIENT_ID>' \
  -d 'client_secret=<CLIENT_SECRET>' \
  -d 'scope=domains' \
  'https://api.wedos.com/oauth2/token'

Exemple : JSON

curl -X POST -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"<CLIENT_ID>","client_secret":"<CLIENT_SECRET>","scope":"domains"}' \
  'https://api.wedos.com/oauth2/token'

Le champ code vaut 1000 lors de l’émission du token, ou 2000 en cas d’erreur d’authentification du client ou de requête invalide.

En cas de succès, data contient :

Champ	Description
access_token	Le token, envoyé en tant que Authorization: Bearer <TOKEN>
token_type	Type de token (Bearer)
expires_in	Validité en secondes (3600 par défaut, soit 1 heure)
scope	Les scopes que le token a réellement reçus

{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3d4",
  "data": {
    "access_token": "3f9c2e7a1b...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "domains"
  }
}

Aucun refresh token n’est émis pour client_credentials. Lorsque le token expire, demandez-en un nouveau avec le même appel.

En cas d’erreur, data contient status_code (statut HTTP OAuth2, p. ex. 400 ou 401), error et error_description.

error	Cause
invalid_client	Valeur invalide de client_id ou client_secret, ou le client est bloqué
invalid_request	grant_type ou une autre valeur obligatoire est manquante, ou la méthode n’était pas POST
unsupported_grant_type	Valeur non prise en charge du paramètre grant_type .
invalid_scope	Le scope demandé n’existe pas ou n’est pas attribué au client

{
  "code": 2000,
  "msg": "API method error - Bad Request",
  "request_id": "a1b2c3d5",
  "data": {
    "status_code": 400,
    "error": "invalid_client",
    "error_description": "The client credentials are invalid"
  }
}

Envoyez la valeur de data.access_token dans l’en-tête Authorization lorsque vous appelez un endpoint v2 couvert par le scope du token.

Exemple :

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/domains'

Efforcez-vous de respecter les bonnes pratiques suivantes :

• Conservez le token et réutilisez-le jusqu’à son expiration (expires_in). Ne demandez pas un nouveau token avant chaque appel de l’API.
• Si un endpoint v2 renvoie une erreur d’authentification (2000), demandez un nouveau token et réessayez l’appel.
• Ne demandez que les scopes dont votre application a besoin et utilisez Lecture seule pour les clients qui ne modifient jamais de données.
• Dans la mesure du possible, limitez chaque client à des adresses IP connues.
• Créez un client distinct pour chaque application, afin de pouvoir en désactiver ou en supprimer un sans affecter les autres.

Configuration recommandée pour les équipes

Si plusieurs personnes ont accès à l’API, nous recommandons la configuration suivante :

• Un client API par personne ou par système. Le log montre qui a effectué chaque requête et, lorsque quelqu’un part, vous ne bloquez que son client.
• Uniquement les scopes nécessaires. Un client pour le DNS n’a pas besoin d’accéder aux domaines.
• « Lecture seule » partout où cela suffit – surveillance, rapports, contrôles d’état.
• Limitation aux adresses IP des serveurs ou des réseaux qui appellent réellement l’API.
• Expiration du token. Définissez une durée de validité et renouvelez le token régulièrement.
• Conservez la clé secrète du client uniquement côté serveur – jamais dans un navigateur, une application mobile ou un dépôt public.

Lorsque quelqu’un part :

1. Bloquez ou supprimez son client API dans la liste des clients. Tous ses tokens cessent immédiatement de fonctionner et aucun nouveau token ne peut être demandé pour lui. Les autres clients ne sont pas affectés.
2. Si quelqu’un d’autre reprend son travail, veillez toujours à créer un nouveau client pour cette personne.

---

Journalisation des requêtes

La section HTTP REST API de l’administration contient un log des requêtes. Vous pouvez le filtrer par scope d’autorisation, client API, statut et méthode HTTP.

Pour accéder au log, procédez comme suit :

1. Connectez-vous à l’administration client.
2. Accédez à l’interface WEDOS REST API (actuellement indisponible).
3. Cliquez sur le bouton Afficher le log des requêtes HTTP REST API .

Chaque client de la liste dispose en outre d’un lien log , qui ouvre le log filtré sur les requêtes de ce client.

Pour chaque requête, nous enregistrons :

• la date et l’heure, ainsi que l’adresse IP d’où provient la requête,
• le client API (ID et nom) et le scope d’autorisation,
• la méthode HTTP, l’URL et la commande exécutée,
• les données d’entrée et la réponse de l’API (résultat et code de retour).

Nous n’enregistrons pas :

• l’access token ni la clé secrète du client – l’en-tête Authorization n’est pas conservé dans le log des requêtes et le token est masqué dans les enregistrements internes de WEDOS,
• les valeurs sensibles dans les données d’entrée (mots de passe et similaires) sont stockées masquées.

Autres informations importantes :

• Les données d’entrée et la réponse sont stockées ensemble jusqu’à 1 024 caractères. Tout contenu plus long est tronqué.
• Les enregistrements sont conservés pendant 90 jours, après quoi ils sont supprimés automatiquement.
• Le log ne peut pas encore être exporté ni lu via l’API. Il n’est disponible que dans l’administration client.

---

Questions fréquentes