DNS API

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: :  

 

 

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:

  • jti als „global eindeutige“ Kennung.

  • iss und sub als Anmeldename des Benutzers.

  • aud als Zeichenfolge „BrandShelter“.

  • nbf muss ein Zeitstempel in der Vergangenheit sein. Der Anspruch „nbf“ (not before) gibt den Zeitpunkt an, vor dem das JWT nicht gültig ist.

  • iat muss ein Zeitstempel in der Vergangenheit sein. Der Anspruch „iat“ (issued at) gibt den Zeitpunkt an, zu dem das JWT ausgestellt wurde.

  • exp muss 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:

  • kid muss der Anmeldename des Benutzers und der Name des Zugriffstokens sein, getrennt durch einen Schrägstrich, z. B. "john.doe@brandshelter.com/ExampleToken".

  • alg muss „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  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:

240813_EN_DNS API Guide.pdf

240202_EN_Premium DNS_BrandShelter.pdf

 

 

More articles in this section