Cet article vous aidera à utiliser notre API DNS.
Qu'est-ce que l'API DNS ?
L'API de gestion DNS de BrandShelter, basée sur GraphQL, est une interface de programmation applicative qui permet aux utilisateurs d'automatiser les mises à jour et la gestion des enregistrements DNS pour tous leurs domaines, réduisant ainsi la complexité et les erreurs.
GraphQL est un langage de requête et un runtime pour les API qui offre une approche flexible et efficace pour interroger, mettre à jour et s'abonner aux données.
Les systèmes basés sur GraphQL communiquent généralement via HTTP et utilisent un point de terminaison unique pour toutes les requêtes et mutations. GraphQL permet aux utilisateurs de ne demander que les données dont ils ont besoin et définit un système de types pour garantir que les données demandées sont au bon format.
L'accès à l'API respecte les permissions de l'utilisateur dont le jeton est utilisé. Les mêmes permissions que pour le portail s'appliquent. Ainsi, chaque utilisateur n'aura pas accès à d'autres domaines / zones / divisions, etc., simplement en utilisant l'API.
Sommaire
-
Introduction
Point de terminaison API GraphQL
-
Autorisation
Jetons d'accès
JWT (JSON Web Token)
HTTP Authentification du Porteur
Introspection & Auto Documentation
Exemples
Documentation
Introduction
Point de terminaison API GraphQL
Nous proposons un point de terminaison GraphQL pour interagir avec l'API DNS pour nos clients (inscription & connexion requises).
Pour l'environnement de production :
https://secure.brandshelter.com/graphql
Pour l'environnement de démonstration (OTE) :
https://demo.brandshelter.com/graphql
Voici une excellente solution pour en savoir plus sur GraphQL : Introduction à GraphQL | GraphQL
Autorisation
Jetons d'accès
Vous pouvez gérer vos jetons d'accès dans l'application frontend de BrandShelter. La clé d’API (ou clé d’accès) liée au jeton est requise pour générer un JWT valide, utilisé ensuite pour accéder à l’API DNS.
https://secure.brandshelter.com/access_tokens
→ Cliquez sur le bouton "Créer un nouveau token/jeton d’accès"
Saisissez un nom et une date d'expiration pour créer votre token
JWT (JSON Web Token) (à générer sur le portail BrandShelter)
Pour obtenir un JWT adapté à l'accès à l'API GraphQL, vous avez besoin d'un utilisateur avec un token/jeton d'accès valide et non expiré. Une fois le token créé, vous pouvez ensuite créer un JWT directement sur votre portail client BrandShelter : https://secure.brandshelter.com/access_tokens
→ Une fois le token créé, clic droit sur le token ou bien cliquez sur l'icône des 3 barres horizontales pour ouvrir le menu, puis cliquez sur "Générer JWT".
Information complémentaire
Le JWT est signé avec le contenu suivant :
jtien tant qu'identifiant « globalement unique ».issetsuben tant que nom d’utilisateur (login).audla chaîne de caractères « BrandShelter ».nbfdoit être un horodatage dans le passé. La revendication "nbf" (not before) identifie le moment avant lequel le JWT n'est pas valide.iatdoit être un horodatage dans le passé. La revendication "iat" (issued at) identifie le moment où le JWT a été émis.expdoit être un horodatage dans le futur. La revendication "exp" (expiration time) identifie le moment d'expiration à partir duquel le JWT n'est plus valide.
Ce JWT est signé en utilisant la clé du jeton d'accès avec l'algorithme « HS512 » (HMAC avec SHA-512).
Certains en-têtes JWT sont définis comme suit :
kiddoit être le nom de connexion de l'utilisateur et le nom du jeton d'accès séparés par une barre oblique, par exemple,"john.doe@brandshelter.com/ExampleToken".algdoit être « HS512 ».
Exemple d'en-tête JWT :
{
"kid": "john.doe@brandshelter.com/ExampleToken",
"alg": "HS512"
}
Exemple de chargement (payload) JWT :
{
"iss": "john.doe@brandshelter.com",
"sub": "john.doe@brandshelter.com",
"aud": "BrandShelter",
"nbf": 1680522050,
"exp": 1712102400,
"iat": 1680594434,
"jti": "BrandShelter-7a589414-d004-46b4-a95f-50b763f678d3"
}
Vous pouvez utiliser 
JWT.IO pour créer ou vérifier les JWT.
HTTP Authentification du Porteur
Pour l'authentification, vous devez envoyer le JWT dans l'en-tête Authorization lors des requêtes à l'API DNS :
Authorization: Bearer <JWT>
Introspection & Auto Documentation
Le système d'introspection GraphQL permet d'interroger des informations sur le schéma disponible. Il existe divers outils et clients capables de générer une documentation API à partir du point de terminaison en direct en utilisant une requête d'introspection. Vous pouvez par exemple utiliser Altair GraphQL Client pour générer et parcourir facilement la documentation de l'API.
Exemples
query CurrentUser {
currentUser {
firstname
lastname
email
}
}
query DnsZone {
dnsZone(domainName: "test-domain-1001.net") {
id
name
zoneType
}
}
query DnsZones {
dnsZones {
nodes {
id
name
zoneType
}
}
}
query DnsRecordsByZone {
dnsRecordsByZone(domainName: "test-domain-1001.net") {
bindSyntax
errors
fqdn
host
id
locked
rdata
ttl
type
}
}
query DnsRecordsByZone {
dnsRecordsByZone(domainName: "test-domain-1002.net", filters: { recordTypes: ["X-WEB-FWD", "A", "AAAA"] }) {
host
id
locked
rdata
ttl
type
}
}
mutation CreateDnsRecord {
createDnsRecord(
input: { type: "MX", dnsZoneId: 2, rdata: "6 mail.foo-1.com." }
) {
id
bindSyntax
}
}
mutation UpdateDnsRecord {
updateDnsRecord(
input: { id: 54, type: "MX", dnsZoneId: 2, rdata: "6 mail.foo-1.com." }
) {
id
bindSyntax
}
}
mutation DeleteDnsRecord {
deleteDnsRecord(id: 2076) {
ids
}
}
mutation PublishDnsZone {
publishDnsZone(domainName: "test-domain-1001.net") {
name
}
}
mutation {
createSecondaryDnsZone(input: {
domainName: "example.com",
managedNameserverSetId: "1",
primaryNameserverIps: ["127.0.0.1"]
}) {
id
name
zoneType
}
}
Documentation
Vous pouvez télécharger et utiliser la documentation suivante pour l'API DNS :