====== Informationen für Entwickler ======

===== Return Code =====
Nach einer Anfrage des Clients (//Request//), antwortet der Server (//Response//, bei DynDNS.org //Return Code// genannt). Wenn mehrere Hostnamen angegeben werden, wird in der Regel auch für den Hostnamen eine Rückmeldung pro Zeile ausgegeben.

Wann kommt welcher //Return Code//?

==== good ====
  * **HTTP-Code:** 200
  * **Bedeutung:** Es ist alles in Ordnung und die gewünschten Änderungen wurden vollständig übernommen.
  * **Anmerkung:** Einem //good// folgt die aktuell gesetzte IP-Adresse.

==== nochg ====
  * **HTTP-Code:** 200
  * **Bedeutung:** Es ist alles in Ordnung, aber es wurden keine Änderungen vorgenommen, denn die Anfrage entsprach schon den Daten im System.
  * **Anmerkung:** Einem //nochg// folgt die aktuell gesetzte IP-Adresse.

==== badauth ====
  * **HTTP-Code:** 401
  * **Bedeutung:** Die Authorisation ist fehlgeschlagen. Die Parameter //username// und/oder //password// sind falsch.

==== badagent ====
  * **HTTP-Code:** 401
  * **Bedeutung:** Die Authorisation ist fehlgeschlagen. Der im HTTP-Header angegeben User-Agent ist nicht zugelassen.
  * **Anmerkung:** //badagent// wird von uns (vorerst) nicht unterstützt.

==== !donator ====
  * **HTTP-Code:** 401
  * **Bedeutung:** Das erbitterte Feature ist dem Client nicht erlaubt.
  * **Anmerkung:** Bei uns ist //jedes// implementierte Feature erlaubt ;-)

==== badsys ====
  * **HTTP-Code:** 400
  * **Bedeutung:** Der Parameter //system// ist ungültig. Gültige Werte sind //dyndns//, //statdns// oder ein Zahlenwert.

==== numhost ====
  * **HTTP-Code:** 400
  * **Bedeutung:** Der Parameter //hostname// ist leer oder gar nicht gesetzt.
  * **Anmerkung:** Eine Begrenzung der maximalen Anzahl von Hostnamen gibt es bei uns nicht.

==== nohost ====
  * **HTTP-Code:** 400
  * **Bedeutung:** Der Parameter //hostname// existiert nicht im System.
  * **Anmerkung:** Unser System macht von diesem //Return Code// keinen Gebrauch. Stattdessen wird ein //abuse// ausgegeben.

==== notfqdn ====
  * **HTTP-Code:** 400
  * **Bedeutung:** Der Parameter //hostname// ist ungültig, da der angegebene Domainname keinem [[:DNS:Fully Qualified Domain Name]] entspricht.

==== !yours ====
  * **HTTP-Code:** 400
  * **Bedeutung:** Es wurde zwar ein Domainname im System gefunden, doch gehört er nicht dem User.
  * **Anmerkung:** Bei uns wird dies mit einem //abuse// quittiert.

==== abuse ====
  * **HTTP-Code:** 400
  * **Bedeutung:** Entweder existiert die als //hostname// angegebene [[:DNS:Zone]] bzw. der [[:DNS:Fully Qualified Domain Name|Domainname]] nicht, ist nicht dynamisch oder gehört nicht dem User.
  * **Anmerkung:** //abuse// wird von DynDNS.org auch dazu benutzt, allzu vielen Anfragen einen Riegel vorzuschieben. Das ist uns egal. Das System verkraftet einiges. Sollte es zu exorbitant hohen //Requests// von einzelnen kommen, werden uns die [[:Logging|Log-Einträge]] weiterhelfen.

==== dnserr ====
  * **HTTP-Code:** 500
  * **Bedeutung:** Ein Fehler im DNS-System trat auf.
  * **Anmerkung:** Einem //dnserr// folgt eine nähere Erläuterung. Wir bitten jeden, der so einen //Return Code// bekommt, ihn an unseren [[:Support]] weiterzuleiten. Wir kümmern uns dann darum!

==== 911 ====
  * **HTTP-Code:** 500
  * **Bedeutung:** //911// ist die Notrufnummer in den USA. Bei [[:DDNS]] bedeutet dieser //Return Code//, dass ein fataler Fehler auftrat und der //Request// nicht weiterbearbeitet werden kann.
  * **Anmerkung:** Dem //911// folgt eine nähere Fehlerbeschreibung, die sehr hilfreich sein kann. Sollte sie es nicht, bitte an den [[:Support]] wenden!
  * **Fehlerbeschreibungen und Ursachen:**
    * //ddns down//: Der DDNS-Service ist deaktiviert. Das kann bei Wartungsarbeiten schon mal vorkommen.
    * //ssl mode [0|1|2]//: Entweder akzeptiert das System nur noch Anfragen per SSL [2] oder solche Anfragen werden verweigert [0]. [1] bedeutet, dass beide Modi möglich sind.
    * //hostname//, //myip//, //wildcard//, //mx//, //backmx//, //offline// und //ttl// betreffen die jeweiligen Parameter. Diese sollten überprüft werden.

**Wichtig:** Sollten Fehler auftreten, dann sollte der Client keine weiteren Anfragen an unser System stellen, bis der Benutzer eingreift.

Sollte der Service überhaupt nichts zurückliefern, bitten wir, sich an unseren [[:Support]] zu wenden.

===== Request =====
Der //Request// ist eine HTTP- bzw. HTTPS-Anfrage an das System. Wir akzeptieren //HTTP/1.1//.
Benutzername und Passwort werden gemäß den HTTP-Spezifkationen im Header der Anfrage in einem base64-enkodierten String übertragen, alle anderen Daten entweder per GET oder POST.

In der Anfrage enthalten sind die Parameter, die im folgenden näher erklärt werden:

==== username ====
  * **Beschreibung:** Der Benutzname. Er muss im Klartext (//Plain Text//) im Header (HTTP 401) gesendet werden.
  * **mögliche Werte:** ein gültiger Benutzername
  * **Optional:** nein

==== password ====
  * **Beschreibung:** Das Passwort. Es muss im Klartext (//Plain Text//) im Header (HTTP 401) gesendet werden.
  * **mögliche Werte:** ein zum Benutzername passendes Passwort
  * **Optional:** nein

==== system ====
  * **Beschreibung:** Sozusagen ein Profil, das die [[:dns:TTL]] festlegt.
  * **mögliche Werte:** //dyndns// (TTL: 120 Sekunden), //statdns// (3600 Sekunden) oder eine Zahl zwischen 120 und 10800 (3 Stunden). Defaultwert ist //dyndns//.
  * **Optional:** ja

==== hostname ====
  * **Beschreibung:** Welche Domainname soll aktualisiert werden?
  * **mögliche Werte:** ein oder mehrere durch Kommata getrennte Domainnamen. Alternativ ist auch ein Array möglich.
  * **Optional:** nein

==== myip ====
  * **Beschreibung:** Zu welcher IP-Adresse soll der Domainname aufgelöst werden?
  * **mögliche Werte:** eine gültige **öffentliche** IP-Adresse. Sollte der Parameter nicht gesetzt werden, versucht das System, die IP-Adresse selbst zu bestimmen. **Achtung:** Sollte der Client hinter einem Proxy, NAT-Router o.ä. hängen, könnte die IP-Adresse auf ein falsches Ziel verweisen.
  * **Optional:** ja

==== wildcard ====
  * **Beschreibung:** Sollen [[Wildcard|Wildcards]] akzeptiert werden? Diese würden dann wie der angegebene Domainname auf die gleiche IP-Adresse verweisen.
  * **mögliche Werte:** //ON//, //OFF// oder //NOCHG//. Sollte dieser Parameter leer sein, wird er auf //OFF// gesetzt. Defaultwert ist //OFF//.
  * **Optional:** ja

==== mx ====
  * **Beschreibung:** //MX// steht für //Mail Exchanger//. Dies ist ein Eintrag im [[:DNS]], der eine IP-Adresse zu einem Mailserver angibt.
  * **mögliche Werte:** ein gültiger Domainname, eine IP-Adresse, //NOCHG// oder //REMOVE//. //NOCHG// bedeutet, dass der Eintrag im System nicht geändert werden soll, //REMOVE// löscht den Eintrag. Ist der Parameter leer, so wird //REMOVE// angenommen. Defaultwert ist //NOCHG//.
  * **Optional:** ja

==== backmx ====
  * **Beschreibung:** Mehrere Mail Exchanger können im DNS mit unterschiedlichen Prioritäten abgelegt werden, um zum Beispiel Ausfälle zu vermeiden. Soll der im Parameter //mx// angegebene Mail Exchanger als Backup fungieren, muss dieser Parameter mitgesendet werden.
  * **mögliche Werte:** //YES//, //NO//, //NOCHG//. Sollte der Wert leer sein, wird //NO// angenommen. Defaultwert ist //NOCHG//.
  * **Optional:** ja

==== offline ====
  * **Beschreibung:** Soll der Domainname offline gesetzt werden? Sollte dies der Fall sein, werden alle Einträge gelöscht. Siehe auch [[:DDNS#Offline-Status]]
  * **mögliche Werte:** //YES// oder //NO//. Defaultwert ist //NO//.
  * **Optional:** ja

**Anmerkung:** Defaultwerte werden nur bei optionalen Parametern, die **nicht** gesetzt worden sind, vom System gesetzt.

===== Beispiel =====
Beispiele machen das Leben einfacher: Hier anhand eines [[Internet-Browser|Internet-Browsers als Client]].

===== TXT-Datensatz =====
In jeder [[:DNS:Zone]] einer [[:DDNS|dynamischen Domain]] existiert ein besonderer TXT-Datensatz,
der Hinweise auf das letzte Update-Datum der Domain gibt. Das Format ist "c=//Timestamp//", wobei der Timestamp dem Unix-Timestamp zum letzten Update auf dem Server entspricht.

Diese Information ist besonders hilfreich, wenn Clients sich z.B. nach dem [[:ddns#Heartbeat]] richten müssen, damit Domains, deren IP sich nicht geändert hat, nicht offline gesetzt werden.

===== Links =====
  * Spezifikationen von DynDNS.org: [[http://www.dyndns.com/developers/specs/]]