Dieser Artikel hilft Ihnen bei der Verwendung unserer DNS API.
Was ist eine DNS API?
Die GraphQL-basierte DNS-Management-API von BrandShelter ist eine Programmierschnittstelle, mit der Benutzer Aktualisierungen und die Verwaltung von DNS-Einträgen für alle ihre Domains automatisieren können, wodurch Komplexität und Fehler reduziert werden.
GraphQL ist eine Abfragesprache und Laufzeitumgebung für APIs, die einen flexiblen und effizienten Ansatz zum Abfragen, Aktualisieren und Abonnieren von Daten bietet.
GraphQL-basierte Systeme kommunizieren typischerweise über HTTP und verwenden einen einzigen Endpunkt für alle Abfragen und Mutationen. GraphQL ermöglicht es Benutzern, nur die benötigten Daten anzufordern, und definiert ein Typsystem, um sicherzustellen, dass die angeforderten Daten das richtige Format haben.
Der API-Zugriff berücksichtigt die Berechtigungen des Benutzers, dessen Token verwendet wird. Es gelten dieselben Berechtigungen wie im Portal. Daher erhält kein Benutzer allein durch die Verwendung der API Zugriff auf andere Domains / Zonen / Divisionen usw.
Zusammenfassung
-
Einführung
GraphQL-API-Endpunkt
-
Autorisierung
Zugriffstoken
JWT (JSON Web Token)
HTTP-Bearer-Authentifizierung
Introspektion und automatische Dokumentation
Beispiele
Dokumentation
Einführung
GraphQL-API-Endpunkt
Wir bieten unseren Kunden einen GraphQL-Endpunkt zur Interaktion mit der DNS API an (Registrierung und Anmeldung erforderlich).
Für die Produktionsumgebung:
https://secure.brandshelter.com/graphql
Für die Demo-(OTE-)Umgebung:
https://demo.brandshelter.com/graphql
Ein guter Ort, um mehr über GraphQL zu erfahren, ist hier: : Einführung in GraphQL | GraphQL
Autorisierung
Zugriffstoken
Sie können Ihre Zugriffstoken in der BrandShelter-Frontend-Anwendung verwalten. Das „Secret“ (API-Schlüssel) eines Zugriffstokens ist erforderlich, um ein gültiges JWT zu erstellen, das für den Zugriff auf die DNS-API verwendet wird.
https://secure.brandshelter.com/access_tokens
→ Klicken Sie auf die Schaltfläche „Create a new token/access token“
Geben Sie einen Namen und ein Ablaufdatum ein, um Ihr Token zu erstellen.
JWT (JSON Web Token) (wird in Ihrem BrandShelter-Portal generiert)
Um ein für den Zugriff auf die GraphQL-API geeignetes JWT zu erhalten, benötigen Sie einen Benutzer mit einem gültigen, nicht abgelaufenen Zugriffstoken. Generieren Sie Ihr JWT im Portal über den Bereich „Access Tokens“, klicken Sie mit der rechten Maustaste auf Ihr Token und klicken Sie auf „Generate JWT“.
Zusätzliche Informationen
Das JWT wird mit den folgenden Inhalten signiert:
jtials „global eindeutige“ Kennung.issundsubals Anmeldename des Benutzers.audals Zeichenfolge „BrandShelter“.nbfmuss ein Zeitstempel in der Vergangenheit sein. Der Anspruch „nbf“ (not before) gibt den Zeitpunkt an, vor dem das JWT nicht gültig ist.iatmuss ein Zeitstempel in der Vergangenheit sein. Der Anspruch „iat“ (issued at) gibt den Zeitpunkt an, zu dem das JWT ausgestellt wurde.expmuss ein Zeitstempel in der Zukunft sein. Der Anspruch „exp“ (expiration time) gibt den Ablaufzeitpunkt an, ab dem oder nach dem das JWT ungültig ist.
Dieses JWT wurde mit dem „Secret“ des Zugriffstokens unter Verwendung des Algorithmus „HS512“ (HMAC mit SHA-512) signiert. Einige JWT-Header werden wie folgt entsprechend gesetzt:
kidmuss der Anmeldename des Benutzers und der Name des Zugriffstokens sein, getrennt durch einen Schrägstrich, z. B."john.doe@brandshelter.com/ExampleToken".algmuss „HS512“ sein.
Beispiel für einen JWT-Header:
{
"kid": "john.doe@brandshelter.com/ExampleToken",
"alg": "HS512"
}
Beispiel für eine JWT-Nutzlast:
{
"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"
}
Sie können
JWT.IO zum Erstellen oder Überprüfen von JWTs verwenden.
HTTP-Bearer-Authentifizierung
Zur Authentifizierung müssen Sie das JWT im Authorization-Header senden, wenn Sie Anfragen an die DNS-API stellen:
Authorization: Bearer <JWT>
Introspektion und automatische Dokumentation
Das GraphQL-Introspektionssystem ermöglicht die Abfrage von Informationen über das verfügbare Schema. Es gibt verschiedene Tools und Clients, die mithilfe einer Introspektionsabfrage eine API-Dokumentation aus dem aktiven Endpunkt generieren können. Sie können beispielsweise den Altair GraphQL Client verwenden, um die API-Dokumentation einfach zu generieren und zu durchsuchen.
Beispiele
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
}
}
Dokumentation
Sie können die folgende Dokumentation für die DNS API herunterladen und verwenden:
240202_EN_Premium DNS_BrandShelter.pdf