Cet article est destiné à vous aider à utiliser notre API DNS.
Qu'est-ce que l'API DNS ?
L’API (Application Programming Interface) de gestion DNS de SafeBrands basée sur GraphQL est une interface de programmation d’applications qui permet aux utilisateurs et clients SafeBrands 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 environnement d’exécution pour les APIs qui offrent une approche flexible et efficace du requêtage, de la mise à jour et de l’abonnement 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 modifications (mutations). GraphQL permet aux utilisateurs de demander uniquement les données dont ils ont besoin et définit un système de types (type system) pour s’assurer que les données demandées sont dans le bon format.
Sommaire
- Introduction
- GraphQL API
- Autorisation
- Jetons d'accès (Tokens)
- JWT (JSON Web Token)
- HTTP Authentification du Porteur
- Introspection & Auto Documentation
- Exemples
- Documentation
Introduction
GraphQL API
Nous proposons un point de terminaison GraphQL pour interagir avec l’API DNS pour nos clients (inscription et connexion requises).
Pour l'environnement de production :
https://secure.brandshelter.com/graphql
Pour l'environnement de demo (OTE) :
https://demo.brandshelter.com/graphql
Voici une excellente solution pour en savoir plus sur GraphQL : Introduction to GraphQL | GraphQL
Autorisation
Jetons d'accès (Tokens)
Vous pouvez gérer vos jetons d’accès sur votre Portail SafeBrands. Le « secret » d’un jeton d’accès est nécessaire pour créer un JWT valide qui est utilisé pour accéder à l’API DNS.
https://home.safebrands.com/access_tokens
JWT (JSON Web Token)
Pour obtenir un JWT (JSON Web Token) adapté à l’accès à l’API GraphQL, vous avez besoin d’un utilisateur disposant d’un jeton d’accès (token) valide et non expiré. À l’aide du "secret" de ce jeton, vous pouvez ensuite créer et signer un JWT avec du contenu :
-
jticomme identifiant « unique global ». -
issetsubcomme identifiant de l'utilisateur. -
audcomme la chaîne “SafeBrands”. -
nbfdoit être un horodatage dans le passé. La commande « nbf » (pas avant) identifie le moment avant lequel le JWT n’est pas valide. -
iatdoit être un horodatage dans le passé. La commande « iat » (émis / délivré à) indique l’heure à laquelle le JWT a été émis / délivré. -
expdoit être un horodatage dans le futur. La commande « exp » (heure d’expiration) identifie l'heure d’expiration à partir de laquelle le JWT n’est plus valide.
Vous signez ensuite ce JWT à l’aide du « secret » du jeton d’accès avec l’algorithme « HS512 » (HMAC avec SHA-512). Pour ce faire, vous devez vous assurer que certains en-têtes JWT sont définis de manière appropriée :
-
kiddoit être l'identifiant de connexion de l’utilisateur et le nom du jeton d’accès séparés par une barre oblique (slash), par ex.,"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 vos JWTs.
HTTP Authentification du Porteur
Pour l’authentification, vous devez envoyer le JWT dans l’en-tête Authorization lorsque vous envoyez des requêtes à l’API DNS :
Authorization: Bearer <JWT>
Introspection & Auto Documentation
Le système d’introspection GraphQL permet de demander des informations sur le schéma disponible. Il existe différents outils et clients capables de générer une documentation d’API directement à partir du point de terminaison à l’aide d’une requête d’introspection. Vous pouvez utiliser par exemple 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
}
}
Documentation
Vous pouvez télécharger et utiliser la documentation suivante pour en savoir plus et utiliser l’API DNS (en anglais) :
EN_DNS API_Product sheet_BrandShelter.pdf
240313_DNS API Documentation_BrandShelter.pdf