Details DISPOROOM Rest API
Die API bietet eine Reihe von Funktionsaufrufen, die es erlauben Rauminformationen abzurufen und Raumbuchungen anzulegen. Jeder Funktionsaufruf benötigt seinerseits eine Reihe von Parametern, wobei der sog. "apikey" bei jedem Funktionsaufruf zwingend erforderlich ist.
Der Rückgabewert ist entweder JSON-Text oder im Fall eines Bildes direkt die Bilddaten.
Nutzen Sie den ausführlich dokumentierten Quellcode dieser Demo als Template für Ihre eigene Implementierung. Um die API zu testen bietet sich die Verwendung eines Rest-Clients an. Z.B. http://restclient.net/
API key erzeugen
Im Formular der Systemeinstellungen kann eine Zufallszahl generiert werden, die in Kombination mit Ihrem Accountnamen den kompletten Schlüssel ergibt. Z.B. "account.123456"
Raum zur öffentlichen Buchung freigeben
Um auf Informationen eines Raumes öffentlich zugreifen zu können muß der Raum zunächst durch den Administrator im Formular Raumeigenschaften entsprechend freigegeben werden.
Ist das Feld "Verwaltervergabe" angewählt, werden durch den öffentlichen Buchungsvorgang lediglich Raumanfragen angelegt, die vom einem Raumverwalter explizit bestätigt werden müssen. (In der Demo weden diese im Buchungskalender GELB dargestellt). Ist das Feld nicht angelegt, kann der Raum direkt gebucht werden (ROT dargestellt).
GET request an
http://www.disporoom.com/application/
Die Abfrage liefert eine JSON Antwort als Liste mit Informationen zu allen gefundenen öffentlich buchbaren Räumen im angegebenen Zeitraum und in der angegebenen Sprache. Wird kein Zeitraum angegeben, werden alle öffentliche buchbaren Räume geliefert. Wird keine Sprache angegeben, wird zunächst versucht die vom Browser übermittelte Sprache zu verwenden, ansonsten die default Sprache des DISPOROOM Servers.
Folgende Parameter werden unterstützt (* erforderlich):
- apikey* : Zugriffsschlüssel als String : umweltverein.b31726cb1e14c8d9
- start : Startzeitpunkkt als IsoDate String : 2015-05-26T12:00:00.000Z
- end : Endzeitpunkkt als IsoDate String: 2015-05-27T16:00:00.000Z
- lang : Sprache in der Antwort als String : en
Beispiel Request :
https://disporoom.com/application/api/rooms?apikey=umweltverein.b31726cb1e14c8d9&start=2015-05-26T12:00:00.000Z&end=2015-05-27T16:00:00.000Z&lang=en
Beispiel Response:
[
{
"id": 6,
"name": "Seeblick",
"code": "sb",
"price": 2,
"unit": "hour",
"currency": "EUR",
"description": ""
},
{
"id": 8,
"name": "Schnebelhorn",
"code": "sh",
"price": 3,
"unit": "hour",
"currency": "EUR",
"description": "Training room for up to 30 participants. High quality technical equipment. Direct access to the park."
},
{
"id": 10,
"name": "Rone",
"code": "ro",
"price": 2,
"unit": "hour",
"currency": "EUR",
"description": ""
}
]
GET request an
http://www.disporoom.com/application/
Die Abfrage liefert eine JSON Antwort mit Informationen zu dem Raum mit der angegebenen ID (Raumnummer). Wird keine Sprache angegeben, wird zunächst versucht die vom Browser übermittelte Sprache zu verwenden, ansonsten die default Sprache des DISPOROOM Servers.
Folgende Parameter werden unterstützt (* erforderlich):
- apikey* : Zugriffsschlüssel als String : umweltverein.b31726cb1e14c8d9
- lang : Sprache in der Antwort als String : en
Beispiel Request :
https://disporoom.com/application/api/rooms/10?apikey=umweltverein.b31726cb1e14c8d9&lang=en
Beispiel Response:
{"id":10,"name":"Rone","code":"ro","price":2.0,"unit":"hour","currency":"EUR","description":""}
Raumbild laden
Verwendet auf der Demoseite roomReservation.html (mit raumid parameter) und der Startseite index.html
GET request an
http://www.disporoom.com/application/
Die Abfrage liefert das Raumbild (jpg) als octet stream
Folgende Parameter werden unterstützt (* erforderlich):
- apikey* : Zugriffsschlüssel als String : umweltverein.b31726cb1e14c8d9
- cache : max-age cache control Paramter in Sekunden - siehe HTTP/1.1 section 14.9.3
- w : entweder Bildbreite in Pixel (400) oder (250)
- h : oder Bildhöhe in Pixel (100)
Beispiel Request :
https://disporoom.com/application/api/rooms/10/image?apikey=umweltverein.b31726cb1e14c8d9&w=250
Buchungen eines Raumes abrufen
Verwendet auf der Demoseite roomReservation.html (mit raumid parameter)
GET request an
http://www.disporoom.com/application/
Die Abfrage liefert eine JSON Antwort mit den Buchungen des Raumes mit der angegebenen ID (Raumnummer). Wird ein datePattern String angegeben wird dieses Format benutzt um Datumsangaben im JSON Response String zu formatieren. Wird ein status String angegeben werden nur Buchungen mit diesem Status geliefert. Als Status String wird "requested" (Buchungsanfragen) oder "confirmed" (bestätigte Buchungen) unterstützt. Wird keine Sprache angegeben, wird zunächst versucht die vom Browser übermittelte Sprache zu verwenden, ansonsten die default Sprache des DISPOROOM Servers.
Folgende Parameter werden unterstützt (* erforderlich):
- apikey* : Zugriffsschlüssel als String : umweltverein.b31726cb1e14c8d9
- start* : Startzeitpunkkt als IsoDate String : 2015-05-26T12:00:00.000Z
- end* : Endzeitpunkkt als IsoDate String: 2015-05-27T16:00:00.000Z
- datePattern : Datumsformat im Response : yyyy-MM-dd
- status : Status der Buchungen : requested oder confirmed
- lang : Sprache in der Antwort als String : en
Beispiel Request :
https://disporoom.com/application/api/rooms/10/bookings?apikey=umweltverein.b31726cb1e14c8d9&start=2015-05-26T12:00:00.000Z&end=2015-05-27T16:00:00.000Z&lang=en
Beispiel Response:
[
{
"id": 275,
"start": "2015-04-21T05:45Z",
"end": "2015-04-21T10:45Z",
"status": "confirmed"
}
]
GET request an
http://www.disporoom.com/application/
Die Abfrage liefert eine JSON Antwort mit allen Buchungen zu den Räumen mit den gegebenen IDs (Raumnummern) im angegebenen Zeitraum. Wird keine Sprache angegeben, wird zunächst versucht die vom Browser übermittelte Sprache zu verwenden, ansonsten die default Sprache des DISPOROOM Servers.
Folgende Parameter werden unterstützt (* erforderlich):
- apikey* : Zugriffsschlüssel als String : umweltverein.b31726cb1e14c8d9
- start* : Startzeitpunkkt als IsoDate String : 2015-05-26T12:00:00.000Z
- end* : Endzeitpunkkt als IsoDate String: 2015-05-27T16:00:00.000Z
- rooms* : Liste der Raumnummern (roomID) durch Komma getrennt : 6,8,10
- lang : Sprache in der Antwort als String : en
Beispiel Request :
http://localhost:8080/application/api/bookings?apikey=umweltverein.b31726cb1e14c8d9&start=2015-04-20T12:00:00.000Z&end=2015-05-27T16:00:00.000Z&rooms=8,10&lang=en
Beispiel Response:
[
{
"id": 240,
"changed": 1428335200000,
"start": 1429531200000,
"end": 1429603200000,
"topic": "",
"status": "confirmed",
"organizer":
{
"firstname": "Lara",
"lastname": "Weber",
"email": "lara@demo.de",
"phone": ""
},
"participants":
[
],
"room":
{
"id": 8,
"name": "Schnebelhorn",
"code": "sh",
"price": 0,
"unit": null,
"currency": null,
"description": "Training room for up to 30 participants. High quality technical equipment. Direct access to the park."
}
},
{
"id": 275,
"changed": 1429390911000,
"start": 1429595100000,
"end": 1429613100000,
"topic": "",
"status": "confirmed",
"organizer":
{
"firstname": "Ralf",
"lastname": "Wieland",
"email": "ralf@demo.de",
"phone": ""
},
"participants":
[
],
"room":
{
"id": 10,
"name": "Rone",
"code": "ro",
"price": 0,
"unit": null,
"currency": null,
"description": ""
}
},
{
"id": 241,
"changed": 1428337827000,
"start": 1429617600000,
"end": 1429689600000,
"topic": "",
"status": "confirmed",
"organizer":
{
"firstname": "Herta",
"lastname": "Croft",
"email": "herta@demo.de",
"phone": ""
},
"participants":
[
],
"room":
{
"id": 8,
"name": "Schnebelhorn",
"code": "sh",
"price": 0,
"unit": null,
"currency": null,
"description": "Training room for up to 30 participants. High quality technical equipment. Direct access to the park."
}
}
]
GET request an
http://www.disporoom.com/application/
Die Abfrage liefert das Captcha (png) als octet stream
Folgende Parameter werden unterstützt (* erforderlich):
- apikey* : Zugriffsschlüssel als String : umweltverein.b31726cb1e14c8d9
Beispiel Request :
https://disporoom.com/application/api/captcha?apikey=umweltverein.b31726cb1e14c8d9
Formular Post request an
http://www.disporoom.com/application/
Die korrekte Verarbeitung der Formulardaten liefert die erzeugte Buchungsnummer
Folgende Parameter werden unterstützt (* erforderlich):
- apikey* : Zugriffsschlüssel als String : umweltverein.b31726cb1e14c8d9
- room* : interne Raumnummer oder Raumcode (Kurzname) als String : 8 oder sh
- capcha* : Sicherheitsabfrage als String : x67g3
- start* : Startzeitpunkkt als IsoDate String : 2015-05-26T12:00:00.000Z
- end* : Endzeitpunkkt als IsoDate String : 2015-05-27T16:00:00.000Z
- lastname* : Name des Buchenden : Weber
- firstname* : Vorname des Buchenden : Klaus
- email* : E-Mail Adresse des Buchenden : klaus.weber@disporoom.com
- street* : Strasse des Wohnorts : Hauptstrasse 23
- city* : Ort : Hamburg
- zip* : Postleitzahl : 23445
- comment : Zusatztext zur Buchung - Hinweis an den Raumverwalter : Anreise mit öffentlichen Verkehrsmittel/li>
- lang : Sprache des Buchenden (default = de) : en
Beispiel Formular Post :
siehe Quellcode der Demoseite
Response Status Codes
Bei fehlerhaften oder fehlenden Parametern bzw. unbekannter URL erhalten Sie einen entsprechenden Statuscode der programmatisch ausgewertet, oder mit der JavaScript Console des Browsers angezeigt werden kann. Im Response body wird u.U eine detailiertere Fehlermeldung mitgeliefert.
Z.B.: Http Fehler 400 Bad Request
apikey: check format - API key fehlerhaft.
apikey: not found - für den angegenenen Customer existiert kein API key.
apikey: not allowed - der angegebene API key existiert, erlaubt aber nicht den Aufruf dieser Funtion.
wrong ISO date param - Datumsformat nicht ISO 8601 kompatibel
bad user data - Fehler beim verarbeiten der angegebenen Daten.(Zur angegebenen E-Mail existieren bereits andere Angaben)
