Inhalt - Domains

Transcrição

Inhalt - Domains

http.net Domreg API, Version 1.1
Beispiele und Hinweise, Version 2011/05
Inhalt
1.
Allgemeines ..........................................................................................................................................2
1.1 Über dieses Dokument ....................................................................................................................2
1.2 Versionierung und Instanzen ........................................................................................................2
1.3 Protokolle, Zeichenkodierung und Authentifizierung..............................................................2
1.4 Allgemeine Request-Struktur ........................................................................................................3
1.5 Allgemeine Response-Struktur .....................................................................................................3
2.
Handle-Operationen ...........................................................................................................................4
3.
Allgemeine Domain-Operationen ....................................................................................................5
4.
3.1
Domainverfügbarkeit ................................................................................................................5
3.2
Domainverwaltung ....................................................................................................................5
3.3
Löschen und Abgeben von Domains.......................................................................................7
3.4
Initialisieren von Domain-Transfers .......................................................................................7
Verwendung von Extensions ............................................................................................................9
4.1
Zum Konzept der Extension......................................................................................................9
4.2
Beispiel: Info-Ausgabe einer nicht-konnektierten DE-Domain .........................................9
4.3
Beispiel: Erzeugen einer DENIC-AuthInfo1 ......................................................................... 10
4.4
Beispiel: TRADE und KKTRADE einer EU-Domain............................................................... 10
4.5
Beispiel: Registrieren einer IT-Domain mit „it-pin“ ......................................................... 11
© 2011, http.net Internet GmbH
http.net Internet GmbH 2
1. Allgemeines
1.1 Über dieses Dokument
Dies ist eine informelle Ergänzung der Online-Dokumentation mit einigen Beispielen.
1.2 Versionierung und Instanzen
Jede Version der API steht in einer Demo- und einer Live-Instanz zur Verfügung. Beide Instanzen
haben identische Schnittstellen. Die Demo-API ist für Testzwecke und zum Entwickeln von
Clients geeignet. Hier kann das Registrieren und Verwalten von Domains für einige Top-LevelDomains getestet werden, ohne produktive Aufträge zu generieren. Domain-Aufträge werden
an die Test-Systeme der entsprechenden Registrierungsstellen weitergegeben.
•
•
Demo-API:
o Basis-URL: https://api.http.net/1.1/domreg/demo/service.asmx
o Für die Demo-API werden gesonderte Zugangsdaten vergeben.
o Die Demo-API unterstützt folgende Top-Level-Domains: COM, NET, ORG, INFO, BIZ, DE,
AT, EU, CH, NL, IT.
Live-API:
o Basis-URL: https://api.http.net/1.1/domreg/live/service.asmx
o Für die Live-API sind die Zugangsdaten des Partnersystems zu verwenden.
Unter dem Basis-URL befindet sich eine automatisch generierte Schnittstellen-Dokumentation,
die um einige Programmierbeispiele ergänzt ist. Die WSDL-Dienstbeschreibung erhält man aus
dem jeweiligen Basis-URL mit dem Zusatz „?WSDL“, also z.B.:
https://api.http.net/1.1/domreg/live/service.asmx?WSDL
Ab Version 1.1 ist jede API-Instanz durch einen Versionsstring gekennzeichnet, der sich aus
Hostname, Versionsnummer, Schnittstelle und Instanz zusammensetzt. Beispielsweise lautet
der Versionsstring für die Domreg-Demo-API, Version 1.1:
api.http.net/1.1/domreg/demo
Der Versionsstring wird bei jeder Antwort der API ausgegeben.
1.3 Protokolle, Zeichenkodierung und Authentifizierung
Die API unterstützt SOAP 1.1 via HTTPS. Der Server akzeptiert auch SOAP 1.2, von SOAPHeadern wird jedoch kein Gebrauch gemacht.
Als Kodierung sollte grundsätzlich UTF-8 verwendet werden. IDN-Domainnamen können bei
allen Aufträgen wahlweise in Unicode-Form oder als ACE-String angegeben werden.
Die Authentifizierung erfolgt innerhalb der Request-Datensätze.
1.4 Allgemeine Request-Struktur
Ein API-Request hat folgende Basisstruktur:
POST /1.1/domreg/demo/service.asmx HTTP/1.1
Host: api.http.net
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://http.net/API/1.1/ApiMethod"
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ApiMethod xmlns="http://http.net/API/1.1">
<authentication>
<username>userid</username>
<password>password</password>
</authentication>
[Request-Element]
<clTRID>beliebig</clTRID>
</ApiMethod>
</s:Body>
</s:Envelope>
Für ApiMethod ist hier der jeweilige Methodenname einzusetzen.
Das optionale Feld clTRID (Client-Transaction-ID) wird in der Antwort zurückgeliefert. Es kann
Clients mit asynchroner Architektur dazu dienen, die Antwort der Anfrage zuzuordnen.
1.5 Allgemeine Response-Struktur
Die zugehörige Response hat folgende Basisstruktur:
HTTP/1.1 200 OK
Date: Tue, 26 Apr 2011 15:24:55 GMT
Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<ApiMethodResponse xmlns="http://http.net/API/1.1">
<response>
<result>
<code>15000</code>
<message>success: command completed successfully</message>
<details>Der Auftrag wurde erfolgreich ausgefuehrt</details>
<version>api.http.net/1.1/domreg/demo</version>
<date>2011-04-26T17:24:54.7138611+02:00</date>
</result>
<transaction>
<taskID />
</transaction>
[Response-Element]
</response>
</ApiMethodResponse>
</soap:Body>
</soap:Envelope>
Das result-Element enthält folgende Elemente:
• code: 5-stelliger numerischer Antwortcode
• message: statische Kurzbeschreibung des Antwortcodes
• details: ggf. Zusatzinformationen zum Ergebnis. Hier können auch Fehlermeldungen der
Registrierungsstelle enthalten sein.
• version: aktueller API-Versionsstring der aufgerufenen Instanz
• date: Verarbeitungszeitpunkt
Das transaction-Element enthält die gesendete clTRID und je nach Auftragsart eine taskID
(Vorgangsnummer). Diese kann bei Aufträgen, die nicht sofort abgeschlossen werden können,
dazu verwendet werden, um den Status des Vorgangs abzufragen, entweder im Partnerweb
oder mit Hilfe der API-Methode GetTaskStatus.
Die Datenstrukturen im Einzelnen sind dem XML-Schema innerhalb der WSDLDienstbeschreibung zu entnehmen.
2. Handle-Operationen
Kontakt-Datensätze werden mit Hilfe der Methode ContactSave angelegt und verändert. Sendet
der Client eine bestehende Handle-ID mit, wird der entsprechende Datensatz verändert, sofern
die unveränderlichen Daten übereinstimmen. Wenn keine Handle-ID gesendet wird, entscheidet
der Server, ob ein neues Handle angelegt oder ein bestehendes, das im Wesentlichen den
gesendeten Daten entspricht, verändert wird. In jedem Fall liefert er nach erfolgreicher
Ausführung der Aktion das betreffende Handle zurück. Für die Handle-Daten gelten die gleichen
Einschränkungen und Formatierungsregeln wie beim SMTP-Robot.
Das Request-Element der API-Methode ContactSave (ohne Handle-ID) sieht typischerweise etwa
so aus:
<contact>
<type>ORG</type>
<firstname>Test</firstname>
<lastname>Test</lastname>
<org>http.net Internet GmbH</org>
<address>
<street1>Voltastr. 5</street1>
<pcode>13355</pcode>
<city>Berlin</city>
<country>DE</country>
</address>
<email>[email protected]</email>
<phone>+49 30 2100900</phone>
<fax>+49 30 21009090</fax>
<protection>B</protection>
</contact>
Das response-Element in der Antwort enthält das Resultat des Auftrags und einen ContactInfoDatensatz, der das Handle enthält. Mit Hilfe des Handles kann der Datensatz jederzeit über die
API-Methode ContactInfo abgerufen werden.
<response>
<result>
<code>40001</code>
<message>success: contact saved</message>
<details>Die Kontaktdaten wurden erfolgreich gespeichert.</details>
<date>2011-04-27T10:08:48.2128005+02:00</date>
</result>
<transaction>
<taskID />
</transaction>
<contact>
<type>ORG</type>
<firstname>Test</firstname>
<lastname>Test</lastname>
<org>http.net Internet GmbH</org>
<role />
<address>
<street1>Voltastr. 5</street1>
<street2 />
<pcode>13355</pcode>
<city>Berlin</city>
<country>DE</country>
</address>
<email>[email protected]</email>
<phone>+49 30 2100900</phone>
<fax>+49 30 21009090</fax>
<remarks />
<protection>B</protection>
<handle>HIG1-HTTP</handle>
</contact>
</response>
3. Allgemeine Domain-Operationen
3.1
Domainverfügbarkeit
Verfügbarkeitsanfragen können einzeln (DomainAvailable) oder per Bulk (DomainAvailableList)
gestellt werden. Die Bulk-Methode ist im Allgemeinen schneller als eine sequentielle
Einzelprüfung, da die Abfragen serverseitig parallel verarbeitet und nach Möglichkeit im Bulk an
die Registrierungsstellen weitergegeben werden. Es kann jedoch auch sinnvoll sein, clientseitig
asynchron parallele Einzelprüfungen abzusetzen.
Die Verfügbarkeit wird mit Hilfe unterschiedlicher externer Schnittstellen realisiert, deren
Zuverlässigkeit nicht immer gewährleistet ist. Insbesondere bei exotischen TLDs muss teilweise
auf whois-Abfragen zurückgegriffen werden, so dass die Antwort aus einem Cache kommen
oder auch ganz ausfallen kann. Bei allen gTLDs und den meisten europäischen ccTLDs ist die
Abfrage jedoch schnell und zuverlässig.
3.2
Domainverwaltung
Der Verwaltungsstatus einer aktiven Domain des eigenen oder eines Unterkontos kann mit der
API-Methode DomainInfo abgefragt werden. Seit Version 1.1 wird der DomainInfo-Datensatz bei
folgenden Methoden zurückgegeben:
•
•
•
•
DomainInfo
DomainRegister
DomainUpdate
DomainTransferInitiate
Der DomainInfo-Datensatz enthält folgende Felder:
•
name: Der Domainname (Unicode-Form bei IDN-Domains)
•
•
•
•
•
•
•
•
•
•
•
ace-string: ACE-String (gleichlautend zu name bei ASCII-Domains)
active (true/false): gibt an, ob die Domain aktiv berechnet wird
start-date: Startdatum der Berechnung, falls active=true, sonst undefiniert
renew-date: nächstes Wiederberechnungsdatum (i.A. Startdatum + X Jahre)
renew-action (RENEW, CLOSE oder TRANSIT): gibt an ob die Domain zum renew-date
automatisch verlängert wird oder für Löschung, bzw. Transit (nur DE und AT),
vorgemerkt ist
due-notice: letztmöglicher Kündigungstermin zum nächsten renew-date
transfer-answer (ACK oder NACK): die eingestellte Antwort für ausgehende
Transferanfragen
transfer-pending (true/false): gibt an, ob momentan eine ausgehende Transferanfrage
vorliegt
authcode: Der Authcode für ausgehende Transfers (nur relevant, falls die
Registrierungsstelle Transfers mit Authcode unterstützt)
owner-c, admin-c, tech-c, zone-c: Kontakt-Handles
nserver, nsentries: Nameserver-Einträge, bzw. NSEntry-Einträge für DE-Domains
Hier eine Beispiel-Ausgabe für die Domain êxample.com. Sie wurde am 07.05.2008 registriert
und verlängert sich jedes Jahr am 07.05. um ein Jahr, solange sie nicht gekündigt wird. Eine
Abfrage vor dem 07.05.2011 zeigt an, dass sie bis einschließlich 06.05.2011 gekündigt werden
kann (Kündigungsfristen können ja nach TLD variieren):
<domain>
<name>êxample.com</name>
<owner-c>TEST1-HTTP</owner-c>
<admin-c>TEST2-HTTP</admin-c>
<tech-c>TEST3-HTTP</tech-c>
<zone-c>TEST4-HTTP</zone-c>
<nservers>
<nserver>
<name>ns.routing.net</name>
<address>213.160.64.64</address>
</nserver>
<nserver>
<name>ns8.routing.net</name>
</nserver>
</nservers>
<ace-string>xn--xample-hva.com</ace-string>
<active>true</active>
<start-date>2008-05-07T00:00:00</start-date>
<renew-date>2011-05-07T00:00:00</renew-date>
<renew-action>RENEW</renew-action>
<due-notice>2011-05-06T23:59:59</due-notice>
<transfer-answer>NACK</transfer-answer>
<transfer-pending>false</transfer-pending>
<authcode>secret</authcode>
</domain>
Die Kündigung der Domain zum Wiederberechnungstermin kann mit der Methode
DomainSetAutorenew erfolgen. Der folgende Request würde êxample.com für die Kündigung zum
07.05.2011 vormerken, wenn er bis zum 06.05.2011 gesendet wird:
<DomainSetAutorenew xmlns="http://http.net/API/1.1">
<authentication>
<username>username</username>
</authentication>
<domain>xn--xample-hva.com</domain>
<renew>false</renew>
<transit>false</transit>
<clTRID>test</clTRID>
</DomainSetAutorenew>
Über die Veränderung des Verlängerungsstatus wird durch den Domreg-Robot mit einer
RENEWAL-CHANGED Benachrichtigung informiert.
3.3
Löschen und Abgeben von Domains
Für die sofortige Löschung oder Abgabe einer Domain gibt es drei Optionen:
•
•
•
CLOSE: Löschung bei der Registrierungsstelle
TRANSIT: Übertragung an die Registrierungsstelle (nur DE und AT)
ACK: Abgabe an einen anderen Provider
Diese können mit der Methode DomainRelease angewandt werden. Zu beachten ist, dass sich die
Option ACK unterschiedlich auswirkt, je nach TLD und je nachdem, ob eine Anfrage für einen
ausgehenden Transfer für die Domain vorliegt oder nicht (erkennbar am transfer-pending-Wert
der DomainInfo-Ausgabe) Sie bewirkt:
(1) sofortige Zustimmung zum Transfer und Abgabe der Domain, falls eine TransferAnfrage vorliegt,
(2) speichern der Transfer-Antwort ACK für zukünftige Transfer-Anfragen andernfalls.
Bei TLDs, die kein Transfer-ACK unterstützen (z.B. DE) ist die eingestellte Transfer-Antwort
wirkungslos. Zukünftig wird die ACK-Option bei TLDs mit Push-Transfer (z.B. CO.UK) auch eine
aktive Abgabe an einen anderen Provider bewirken, dies ist jedoch momentan noch nicht
implementiert.
Die möglichen Antworten im Erfolgsfall sind:
-
3.4
50201 – success: domain closed bei CLOSE
50202 – success: transit succeeded bei TRANSIT
50104 – success: transfer answer set bei ACK im Fall (2)
15000 – success: command completed successfully bei ACK im Fall (1)
Initialisieren von Domain-Transfers
Eingehende Transfers können mit der Methode DomainTranferInitiate gestartet, bzw.
ausgeführt werden. Je nachdem, ob der Transfer sofort abgeschlossen werden kann oder nicht,
lautet die Antwort im Erfolgsfall:
-
50301 – notify: domain transfer initiated (1), oder
50311 – success: kk succeeded (2)
Bei asynchronem Transfer (1) wird (ggf. nach Abwicklung einer FOA-Bestätigung) der
Transferauftrag an die Registrierungsstelle übergeben. An den Auftraggeber wird eine taskID
(Vorgangsnummer) zurückgegeben:
<DomainTransferInitiateResponse xmlns="http://http.net/API/1.1">
<response>
<result>
<code>50301</code>
<message>notify: domain transfer initiated</message>
<details xsi:nil="true"/>
<date>2011-05-03T12:03:20.5774592+02:00</date>
</result>
<transaction>
<taskID>2011050300005</taskID>
</transaction>
<domain xsi:nil="true" />
</response>
</DomainTransferInitiateResponse>
Über den Status des Auftrages kann man sich mit der Methode GetTaskStatus informieren:
<GetTaskStatus xmlns="http://http.net/API/1.1">
<authentication>
</authentication>
</GetTaskStatus>
Nach erfolgreichem Abschluss des Transfers wird der Status 50311 angegeben:
<GetTaskStatusResponse xmlns="http://http.net/API/1.1">
<response>
<result>
<code>15000</code>
<message>success: command completed successfully</message>
<details>Der Auftrag wurde erfolgreich ausgefuehrt</details>
<date>2011-05-03T13:48:23.8626838+02:00</date>
</result>
<transaction>
<taskID />
</transaction>
<task>
<created>2011-05-03T12:03:17.4</created>
<command>KK</command>
<object>êxample.com</object>
<objectType>domain</objectType>
<userID>userid</userID>
<status>
<code>50311</code>
<message>success: kk succeeded</message>
<details/>
<date>0001-01-01T00:00:00</date>
</status>
</task>
</response>
</GetTaskStatusResponse>
Unabhängig davon informiert der Domreg-Robot per Mail über den Abschluss des Vorgangs. Bei
synchronem Transfer (2) (z.B. DE) wird die Domain sofort übertragen und der AntwortDatensatz zu DomainTransferInitiate enthält bereits die Wiederberechnungsdaten.
4. Verwendung von Extensions
4.1
Zum Konzept der Extension
Eine Extension ist eine Erweiterung von Anfrage- und Antwort-Datensätzen um notwendige
Zusatzinformationen. Sie kann verwendet werden, um
-
seitens der Registrierungsstelle erforderliche Zusatzinformationen in der Anfrage zu
übermitteln,
besondere Zusatzinformationen zum Domain-Status im Antwort-Datensatz
bereitzustellen oder
den Auftrag zu erweitern oder zu modifizieren.
Extensions werden als Key-Value-Parameter formatiert, wobei der Key-Teil festgelegt ist und
der Value-Teil ggf. bestimmten Restriktionen unterliegt.
Die Erweiterung von Kontaktdaten um Zusatzinformationen, die automatisch bei der
Domainregistrierung verwendet werden können, wird ebenfalls über Extensions gesteuert
werden.
4.2
Beispiel: Info-Ausgabe einer nicht-konnektierten DE-Domain
Extensions werden verwendet, um wichtige Zusatzinformationen zum Domainstatus
anzugeben. Bei einer DE-Domain, deren Konnektierung von DENIC nicht akzeptiert wurde, droht
Löschung des Domainnamens durch DENIC, wenn der Fehler nicht behoben wird. Der DomainInfoDatensatz enthält einen entsprechenden Hinweis in einer Extension:
<domain>
<name>nicht-konnektiert.de</name>
<nservers>
<nserver>
<name>ns1.nicht-konnektiert.de</name>
</nserver>
<nserver>
<name>ns2.nicht-konnektiert.de</name>
</nserver>
</nservers>
<extension>
<key>DENIC</key>
<value>The status of the domain is failed</value>
</extension>
<ace-string>nicht-konnektiert.de</ace-string>
<authcode xsi:nil="true" />
</domain>
4.3
Beispiel: Erzeugen einer DENIC-AuthInfo1
Für DE-Domains kann ein AuthInfo1 mit der Methode DomainTransferCreateAuthcode erzeugt
werden. Dieser ist entsprechend den DENIC-Richtlinien gültig, also maximal 30 Tage. Wenn für
eine DE-Domain ein AuthInfo1 aktiv ist, zeigt der DomainInfo-Datensatz diesen im Feld
authcode an und gibt das Ablaufdatum in einer Extension an:
<domain>
<name>example.de</name>
<nsentries>
<nsentry>example.de IN A 127.0.0.1</nsentry>
</nsentries>
<extension>
<key>AuthInfo1</key>
<value>2011-06-02</value>
</extension>
<ace-string>example.de</ace-string>
<authcode>E4S8YpvU3342</authcode>
</domain>
4.4
Beispiel: TRADE und KKTRADE einer EU-Domain
Bei TLDs, die keinen Inhaberwechsel innerhalb eines gewöhnlichen Updates erlauben, kann ein
TRADE gesendet werden, indem man den Datensatz einer DomainUpdate-Anfrage entsprechend
modifiziert:
<DomainUpdate xmlns="http://http.net/API/1.1">
<authentication>
</authentication>
<domain>
<name>example.eu</name>
<owner-c>NEU1-HTTP</owner-c>
<nservers>
<nserver>
</nserver>
<nserver>
</nserver>
</nservers>
<extension>
<key>command</key>
<value>TRADE</value>
</extension>
</domain>
</DomainUpdate>
Ebenso kann ein DomainTransferInitiate-Auftrag für EU-Domains zu einem KKTRADE
(gleichzeitiger Provider- und Inhaberwechsel) modifiziert werden:
<extension>
<key>command</key>
<value>KKTRADE</value>
</extension>
4.5
Beispiel: Registrieren einer IT-Domain mit „it-pin“
Bei einigen Registrierungsstellen sind Zusatzangaben für die Domainregistrierung erforderlich,
die in Extensions angegeben werden können. Beispielsweise erfordert die Registrierung einer ITDomain die Angabe einer Identifikationsnummer, der so genannten „it-pin“:
<domain>
<name>example.it</name>
<nservers>
<nserver>
</nserver>
<nserver>
</nserver>
</nservers>
<extension>
<key>it-pin</key>
<value>DE999999999</value>
</extension>
</domain>

Inhalt - Domains

Transcrição

Documentos relacionados

Soundkarte ultron PCI 7.1 Kanal Octosound retail Artikel

Linkaufbau für Webdesigner (und Warum du den Trick auch nuTzen

Vordruck für Mitteilung - Lehrstuhl für Aerodynamik und

KAUFVERTRAG über die Internet-Domain - Domain

Referenz: Generic Java Ontology API Thema: Eclipse Plug

VERTRAG zur Erstellung einer Website

interWays :: Bestehende Adresse weiternutzen

Web Cryptography API

Schneller Einstieg Schnelle Erfolgserlebnisse Reduzierung der

wife cheating