Technische Details
Das API versteht sowohl GET als auch POST Anfragen. GET Anfragen müssen URL-encoded sein. Als Charset wird UTF-8 verwendet. Der Name darf sowohl in Groß- wie auch Kleinschreibung angegeben werden (case-insensitive). Der Übersichtlichkeit halber sollten die Namen aber in Großschreibung angegeben werden. Nummerierungen in Parametern beginnen immer mit 1 und müssen fortlaufend sein. Wenn also ein Parameter mit z.B. PARAMETER1...n angegeben ist, dann heißt das, dass z.B. folgende Übergabe möglich ist: PARAMETER1=27&PARAMETER2=15&PARAMETER3=9
Folgendes ist nicht erlaubt (überspringen von Nummern): PARAMETER1=27&PARAMETER4=15&PARAMETER6=9
Ja / Nein Parameter, d.h. True / False werden mit 1 bzw. 0 codiert.
Die Reihenfolge der NVP-Parameter spielt keine Rolle.
Die Antwort des API wird im JSON- oder XML-Format gesendet.
(Verkürztes) Beispiel für eine gültige NVP Anfrage:
https://vk.nuernberg.de/export.php?USERNAME=partnername&password=passphrase&...
Folgender String
SUCHTEXT=Bildende Kunst
muss URL-encoded übermittelt werden, was so aussehen würde:
SUCHTEXT=Bildende+Kunst
Eine Antwort des Servers könnte wie folgt aussehen:
<?xml version="1.0" encoding="UTF-8"?>
<ERGEBNIS STATUS="0" version="2.0">
<VERANSTALTUNG ID="17454" GLOBALEID="WILDSTYLE_2012-06-12">
<TITEL>WILDSTYLE</TITEL>
<KURZBESCHREIBUNG>Eine wilde Party im Hirsch</KURZBESCHREIBUNG>
<OEFFNUNGSZEITEN>
<DATUM BEGINN="22:00" ENDE="05:00" EINLASS="">2012-06-12</DATUM>
<OEFFNUNGSZEITEN>
</VERANSTALTUNG>
<ANFRAGEZEIT>2012-04-02 16:45:17</ANFRAGEZEIT>
<AUSGABEZEIT>2012-04-02 16:45:18</AUSGABEZEIT>
</ERGEBNIS>
Einzelne TAGS und PRIVATETAGS werden im Ergebnis mittels || getrennt ausgegeben.
Fehlerbehandlung
Alle Antworten werden mit HTTP-Status 200 ausgeliefert - auch im Fehlerfall. Ob ein Fehler vorliegt, ist daher ausschließlich am Antwort-Body erkennbar, nicht am HTTP-Status.
| Fall | JSON | XML |
|---|---|---|
| Erfolg | kein STATUS-Feld; enthält ANZAHLERGEBNIS/ANZAHLGESAMT und die Treffer |
<ERGEBNIS STATUS="0" …> |
| Login-/Authentifizierungsfehler (ungültige Zugangsdaten in USERNAME/PASSWORD oder USERHASH) | Feld LOGINERROR mit Klartext-Meldung, sonst keine Treffer |
<ERGEBNIS STATUS="99"><FEHLER><![CDATA[…]]></FEHLER></ERGEBNIS> |
| Keine Treffer | reguläre Erfolgsantwort mit ANZAHLERGEBNIS=0 |
<ERGEBNIS STATUS="0" …> ohne VERANSTALTUNG-Knoten |
Das Feld STATUS (nur XML) bedeutet: 0 = Erfolg, 99 = Login-/Authentifizierungsfehler.
Login-Fehler im Detail
Ein Login-Fehler kann folgende Ursachen haben:
| Ursache | Meldung (sinngemäß) |
|---|---|
| Benutzername oder Passwort falsch | „Sie haben einen falschen Benutzernamen oder ein falsches Passwort eingegeben!" |
| USERHASH unbekannt | „Sie haben einen falschen Hash eingegeben!" |
| Zugang noch nicht aktiviert | „Ihr Zugang wurde noch nicht aktiviert …" |
| Zu viele Fehlversuche | „Sie haben zu oft falsche Zugangsdaten eingegeben. Der Login ist jetzt für n Sekunden gesperrt." |
Ausgegeben wird ausschließlich der Klartext der Meldung, kein maschinenlesbarer Fehlercode. Prüfen Sie deshalb clientseitig nur, ob LOGINERROR (JSON) bzw. STATUS="99" (XML) vorliegt, und werten Sie den Meldungstext nicht maschinell aus – die Texte können sich ändern und HTML-Entities enthalten (z.B. für).
Liegt ein Login-Fehler vor, werden keine Veranstaltungsdaten ausgegeben. Es gibt insbesondere keinen stillen Rückfall auf die anonyme (öffentliche) Abfrage: Wer mit fehlerhaften Zugangsdaten anfragt, erhält eine Fehlermeldung und kein Ergebnis.
Nach mehreren fehlgeschlagenen Login-Versuchen von derselben IP-Adresse wird der Login vorübergehend gesperrt; die Meldung nennt die verbleibende Sperrzeit in Sekunden. Brechen Sie bei einem LOGINERROR daher ab, statt die Abfrage in einer Schleife zu wiederholen – wiederholte Fehlversuche verlängern die Sperre nur.
Zeitzone
Alle in Anfragen und Antworten verwendeten Datums- und Uhrzeitwerte sind lokale Zeit der Zeitzone Europe/Berlin (MEZ/MESZ, inkl. automatischer Sommer-/Winterzeit) und enthalten keinen UTC-Offset. Das betrifft sowohl die ausgegebenen Felder (z.B. DATUMSTART, DATUMENDE, ERSTERTERMIN, LETZTEAENDERUNG) als auch die Filter-Parameter (START_DATUM, ENDE_DATUM, START_ZEIT, ENDE_ZEIT, STARTZEITRAUM, UPDATE), die serverseitig als Europe/Berlin interpretiert werden.
Wer in einer anderen Zeitzone rechnet, muss seine Abfragegrenzen und die ausgegebenen Zeiten entsprechend umrechnen – andernfalls können z.B. Termine kurz nach Mitternacht auf den benachbarten Tag fallen und aus dem angefragten Zeitraum herausfallen.