REST API – NSSET de domaine

WEDOS REST API est encore en développement. L’accès et les fonctionnalités peuvent changer sans préavis.

Cet article couvre partiellement l’endpoint Domains de WEDOS REST API. Les domaines et les contacts de domaine font l’objet d’articles distincts. Pour WEDOS API (WAPI), voir WAPI – Domaines WEDOS.

Pour obtenir des informations de base sur WEDOS REST API, consultez le Manuel WEDOS REST API.

Dans cet article, vous trouverez les informations suivantes :

NSSETs Endpoint Access

Un NSSET est un ensemble nommé de serveurs DNS qui peut être géré séparément et affecté à plusieurs domaines à la fois (utilisé principalement pour les domaines .cz). Cette API couvre la gestion des NSSETs sous le préfixe /v2/nssets de l’URL.

URL de base et authentification

The base URL for the NSSETs endpoints is: https://api.wedos.com/v2

Toute la communication passe par HTTPS et l’authentification utilise uniquement OAuth2 : envoyez l’en-tête Authorization: Bearer <TOKEN> avec chaque requête. Le token doit disposer du scope domains (un scope unique partagé par les domaines, les contacts et les NSSETs). Sans authentification valide, l’API renvoie une erreur.

Les requêtes contenant des données (POST/PATCH) sont envoyées au format JSON (Content-Type: application/json).

Vous pouvez ajouter le paramètre example=1 à n’importe quel endpoint (par ex. ?example=1, ou &example=1 si l’URL contient déjà d’autres paramètres de requête). Au lieu d’exécuter la requête, l’API renvoie alors un exemple de commande curl pour cet appel. Une authentification valide est requise même dans ce mode.

Aperçu des endpoints

MéthodeEndpointDescription
GET/nssets/checkVérifier la disponibilité ou l’existence d’un NSSET
GET/nssets/{name}Informations sur le NSSET
POST/nssetsCréer un NSSET
POST/nssets/{name}/transferTransférer un NSSET
POST/nssets/{name}/auth-info/sendEnvoyer le code d’autorisation du NSSET
PATCH/nssets/{name}Modifier un NSSET

Format de la réponse

La réponse de l’API est toujours un objet JSON contenant les clés code (code de retour), msg (description textuelle), request_id (identifiant de la requête) et, le cas échéant, data (données renvoyées en cas de succès).

Outre les codes de retour spécifiques (métier) indiqués ci-dessous pour chaque appel, tous les endpoints peuvent également renvoyer ces codes généraux de la couche REST :

  • 1000 – la requête a été exécutée avec succès
  • 2000 – authentification (token Bearer OAuth2) manquante ou invalide
  • 2004 – taille maximale autorisée de la requête dépassée (URL ou corps de la requête)
  • 4000 – méthode ou action d’API inconnue ou non prise en charge
  • 4001 – échec de la validation des données d’entrée
  • 4005 – aucun exemple défini pour la forme d’URL actuelle avec example=1 activé
  • 6000 – erreur interne lors de l’initialisation du traitement de la requête

GET /nssets/check

Vérifie si un handle de NSSET est libre et quel est son statut auprès du registre.

Paramètres :

  • tld – obligatoire, query, string – TLD pour lequel le NSSET est vérifié
  • name – obligatoire, query, string – handle du NSSET
  • reg_key – facultatif, query, string – identifiant d’un registre précis

Codes de retour :

  • 1000 – le NSSET est disponible à l’enregistrement
  • 2100 – paramètre obligatoire manquant
  • 2101 – paramètres d’entrée invalides
  • 2201 – TLD invalide
  • 2247 – format de NSSET non pris en charge
  • 3242 – le NSSET est indisponible
  • 3245 – le NSSET est déjà enregistré
  • 3248 – NSSET indisponible – quarantaine
  • 3249 – NSSET indisponible – réservé
  • 3250 – NSSET indisponible – bloqué
  • 3251 – le NSSET est déjà enregistré chez nous
  • 4218 – échec de la vérification – erreur de communication
  • 5001 – erreur interne d’authentification

Données de réponse : Aucune – le résultat est transmis directement dans les champs de la réponse code/msg.

Exemple :

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/nssets/check?tld=cz&name=NSSET'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g1"
}

GET /nssets/{name}

Renvoie des informations détaillées sur un NSSET, y compris ses serveurs DNS.

Paramètres :

  • name – obligatoire, path – handle du NSSET
  • tld – obligatoire, query, string – TLD
  • reg_key – facultatif, query, string – identifiant d’un registre précis

Codes de retour :

  • 1000 – OK
  • 2100 – paramètre obligatoire manquant
  • 2101 – paramètres d’entrée invalides
  • 2201 – TLD invalide
  • 2209 – erreur de syntaxe
  • 2247 – format de NSSET non pris en charge
  • 3214 – échec du chargement du NSSET
  • 3242 – le NSSET est indisponible
  • 4204 – erreur de connexion

Données de réponse :

  • nsset – objet contenant les informations du NSSET :
    • name – handle du NSSET
    • status – statut du NSSET auprès du registre
    • reg_owner, reg_creator, reg_update – identifiants du bureau d’enregistrement
    • created_date, updated_date, transfer_date – dates de création, de mise à jour et de transfert
    • tech_c – identifiant du contact technique
    • dns.server – tableau des serveurs DNS du NSSET (name, addr_ipv4, addr_ipv6)

Exemple :

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/nssets/NSSET?tld=cz'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g2",
  "data": {
    "nsset": {
      "name": "NSSET",
      "status": "ok",
      "tech_c": "CONTACT",
      "created_date": "2024-01-10",
      "dns": {
        "server": [
          { "name": "ns.wedos.com", "addr_ipv4": null, "addr_ipv6": null },
          { "name": "ns.wedos.org", "addr_ipv4": null, "addr_ipv6": null }
        ]
      }
    }
  }
}

POST /nssets

Crée un nouveau NSSET.

Paramètres :

  • tld – obligatoire, string – TLD pour lequel le NSSET est créé
  • name – facultatif, string – handle de NSSET demandé ; s’il n’est pas indiqué, il est généré automatiquement
  • dns – obligatoire, array – tableau de serveurs DNS sous la forme [{"name":"ns1.example.com","addr_ipv4":"1.2.3.4","addr_ipv6":"..."},...] (addr_ipv4/addr_ipv6 sont facultatifs pour chaque serveur ; même forme que dans POST /domains/create)
  • tech_c – facultatif, string – identifiant du contact technique ; s’il n’est pas indiqué, la valeur par défaut est utilisée
  • reg_key – facultatif, string – identifiant d’un registre précis

Codes de retour :

  • 1000 – OK, NSSET créé
  • 2100 – paramètre obligatoire manquant
  • 2101 – format de paramètre d’entrée invalide
  • 2201 – TLD incorrectement spécifié
  • 2210 – format du tableau de serveurs DNS invalide
  • 2211 – trop de serveurs DNS
  • 2216 – syntaxe de contact invalide
  • 2247 – format de NSSET non pris en charge
  • 3228 – le registre ne prend pas en charge les contacts
  • 3229 – erreur lors du chargement du contact
  • 3242 – le NSSET est indisponible
  • 3244 – échec de la création du NSSET
  • 3245 – le NSSET est déjà enregistré
  • 4212 – erreur de connexion
  • 4218, 4219 – échec de la vérification ou de la création – erreur de communication

Données de réponse :

  • nsset – handle du NSSET créé

Exemple :

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/nssets' \
  --data '{
    "tld": "cz",
    "dns": [
      { "name": "ns.wedos.com" },
      { "name": "ns.wedos.org" }
    ]
  }'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g3",
  "data": {
    "nsset": "NSSET"
  }
}

POST /nssets/{name}/transfer

Transfère vers nous un NSSET depuis un autre bureau d’enregistrement.

Paramètres :

  • name – obligatoire, path – handle du NSSET
  • tld – obligatoire, string – TLD
  • auth_info – obligatoire, string – code d’autorisation du NSSET
  • reg_key – facultatif, string – identifiant d’un registre précis

Codes de retour :

  • 1000 – OK
  • 2100 – paramètre obligatoire manquant
  • 2101 – paramètres d’entrée invalides
  • 2201 – TLD non pris en charge
  • 2215 – auth_info manquant
  • 2247 – nom de NSSET invalide
  • 2249 – le transfert de NSSET n’est pas autorisé pour ce TLD
  • 3214 – échec du chargement du NSSET
  • 3242 – NSSET non pris en charge
  • 3251 – le NSSET est déjà enregistré auprès du bureau d’enregistrement cible
  • 3255 – erreur d’autorisation
  • 3256 – échec du transfert du NSSET
  • 4221 – échec du transfert – erreur de connexion

Données de réponse : Aucune – le résultat est transmis directement dans les champs de la réponse code/msg.

Exemple :

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/nssets/NSSET/transfer' \
  --data '{"tld": "cz", "auth_info": "AUTHCODE123"}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g4"
}

POST /nssets/{name}/auth-info/send

Envoie le code d’autorisation du NSSET à l’adresse e-mail du contact technique.

Paramètres :

  • name – obligatoire, path – handle du NSSET
  • tld – obligatoire, string – TLD
  • reg_key – facultatif, string – identifiant d’un registre précis

Codes de retour :

  • 1000 – OK, code d’autorisation envoyé à l’adresse e-mail du contact
  • 2100 – paramètre obligatoire manquant
  • 2101 – paramètres d’entrée invalides
  • 2201 – TLD non pris en charge
  • 2243 – l’envoi du code d’autorisation n’est pas autorisé pour ce NSSET
  • 3214 – échec du chargement du NSSET
  • 3217 – échec de l’envoi du code d’autorisation
  • 3242 – le NSSET est indisponible
  • 4222 – échec de l’envoi – erreur de connexion
  • 5001 – erreur interne d’autorisation

Données de réponse : Aucune – le résultat est transmis directement dans les champs de la réponse code/msg.

Exemple :

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/nssets/NSSET/auth-info/send' \
  --data '{"tld": "cz"}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g5"
}

PATCH /nssets/{name}

Modifie un NSSET existant – ses serveurs DNS, son contact technique ou l’étendue des tests.

Paramètres :

  • name – obligatoire, path – handle du NSSET
  • tld – obligatoire, string – TLD
  • dns – obligatoire, array – tableau de serveurs DNS sous la même forme que dans POST /nssets
  • auth_info – obligatoire, string – code d’autorisation du NSSET
  • tech_c – facultatif, string – identifiant du contact technique ; s’il n’est pas indiqué, il reste inchangé
  • reg_key – facultatif, string – identifiant d’un registre précis
  • report_level – facultatif – étendue des tests effectués par le registre lors de la modification

Codes de retour :

  • 1000 – OK
  • 2100 – paramètre obligatoire manquant
  • 2101 – paramètres d’entrée invalides
  • 2201 – TLD incorrectement spécifié
  • 2209 – erreur de syntaxe
  • 2210 – format du tableau de serveurs DNS invalide
  • 2211 – trop de serveurs DNS
  • 2216 – syntaxe de contact invalide
  • 2247 – NSSET invalide
  • 3214 – échec du chargement du NSSET
  • 3242 – le NSSET n’est pas pris en charge par ce domaine ou ce registre
  • 3252 – erreur d’autorisation
  • 3254 – échec de la modification du NSSET
  • 4204, 4220 – NSSET indisponible ou échec de la modification – erreur de connexion
  • 4212 – contact indisponible – erreur de connexion

Données de réponse : Aucune – le résultat est transmis directement dans les champs de la réponse code/msg.

Exemple :

curl -X PATCH -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/nssets/NSSET-1' \
  --data '{
    "tld": "cz",
    "auth_info": "AUTHCODE123",
    "dns": [
      { "name": "ns.wedos.com" },
      { "name": "ns.wedos.org" }
    ]
  }'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3g6"
}

Remarques

  • Les endpoints sous /v2/domains, /v2/contacts et /v2/nssets sont gérés par une seule classe serveur commune et partagent tous le même scope OAuth2, domains. Du point de vue du client, il s’agit de trois API logiquement distinctes mais administrativement unifiées.
  • Le paramètre dns est fourni sous la forme d’un simple tableau d’objets {"name": "...", "addr_ipv4": "...", "addr_ipv6": "..."}. En interne, il est converti au format hérité utilisé par les anciennes versions de l’API avant l’appel WAPI. Les éléments addr_ipv4 et addr_ipv6 sont facultatifs pour chaque serveur.
  • Pour les NSSETs, le paramètre tld est toujours obligatoire, car le même handle (name) peut en théorie exister auprès de plusieurs registres, et la validation et le format des données diffèrent selon le TLD ou le registre.

Cela vous a-t-il été utile ?

Merci pour votre retour !
Sélecteurs génériques
Correspondances exactes uniquement
Rechercher dans le titre
Rechercher dans le contenu
Sélecteurs de type de contenu
Sommaire de l’article
Parcourir les catégories