Details DISPOROOM Rest API
The API provides a set of function calls that allow to retrieve room information and create room bookings. Each function call requires in turn a number of parameters, the so-called. "Apikey" is imperative at each function call.
The return value is either JSON-text or in the case of an image, the image data directly.
Take the documented source code of this demo as a template for your own implementation. To test the API itself you can use a REST client plug-in for your Browser. For example http://restclient.net/
Generate API key
In the form of the system settings a random number can be generated, which results in the complete key in combination with your account name. For example, "account.123456"
Sharing room for public booking
In order to access public information, the room must first be approved by the administrator by setting the "publicly availiable flag" in the room properties form.
Is the "administrator assignement" field selected, only room requests are created that need to be explicitly confirmed by a room administrator. (The der Demo shows these kind of bookings in YELLOW color). The room can be reserved directly if this flag is not set (marked in RED).
GET request to
http://www.disporoom.com/application/
The query returns a JSON response as a list with information on all publicly available rooms found in the specified period and in the specified language. If no time range is specified, all public bookable rooms are returned. If no language is specified, the language sent by the browser will first be attempted to use, otherwise the default language of Disporoom server is used.
The following parameters are supported (* required):
- apikey* : Access key as a string : umweltverein.b31726cb1e14c8d9
- start : Start time as isodate String : 2015-05-26T12:00:00.000Z
- end : End time as isodate String: 2015-05-27T16:00:00.000Z
- lang : Language used in the response as a string : en
Example 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
Example 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 at
http://www.disporoom.com/application/
The query returns a JSON response with information on the room with the given id (room number). If no language is specified, it is first tried to use the transmitted language by the browser, otherwise the default language of the Disporoom server.
The following parameters are supported (* required):
- apikey* : Access key as a string : umweltverein.b31726cb1e14c8d9
- lang : Language in the response as a string : en
Example Request :
https://disporoom.com/application/api/rooms/10?apikey=umweltverein.b31726cb1e14c8d9&lang=en
Example Response:
{"id":10,"name":"Rone","code":"ro","price":2.0,"unit":"hour","currency":"EUR","description":""}
Get room image
Used on the demo site roomReservation.html (with raumid parameter) and the startpage index.html
GET request at
http://www.disporoom.com/application/
DThe query returns the room image (jpg) as octet stream
The following parameters are supported (* required):
- apikey* : Access key as a string : umweltverein.b31726cb1e14c8d9
- cache : max-age cache control Paramter in seconds - see also HTTP/1.1 section 14.9.3
- w : either image width in pixel (400) or (250)
- h : or image height in pixel (100)
Example Request :
https://disporoom.com/application/api/rooms/10/image?apikey=umweltverein.b31726cb1e14c8d9&w=250
GET request at
http://www.disporoom.com/application/
The query returns a JSON response with the reservations of the room with the given ID (flat number). If a date pattern string specified this format is used to format dates in JSON Response string. If a status string is specified only bookings with this status are delivered. As a status string "requested" (booking requests) or "confirmed" (confirmed bookings) is supported. If no language is specified, the language sent by the browser will first attempt to use, otherwise the default language of the Disporoom server.
The following parameters are supported (* required):
- apikey* : Access key as a string : umweltverein.b31726cb1e14c8d9
- start* : Begin date as IsoDate String : 2015-05-26T12:00:00.000Z
- end* : Enddate as IsoDate String: 2015-05-27T16:00:00.000Z
- datePattern : Dateformat in Response : yyyy-MM-dd
- status : Status of Bookings : requested or confirmed
- lang : Language in the response as a string : en
Example 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
Example Response:
[
{
"id": 275,
"start": "2015-04-21T05:45Z",
"end": "2015-04-21T10:45Z",
"status": "confirmed"
}
]
GET request at
http://www.disporoom.com/application/
The query returns a JSON response with all bookings to the rooms with the given IDs (room numbers) within the specified period. If no language is specified, the language sent by the browser will first attempt to use, otherwise the default language of the Disporoom server.
The following parameters are supported (* required):
- apikey* : Access key as a string : umweltverein.b31726cb1e14c8d9
- start* : Startdate as IsoDate String : 2015-05-26T12:00:00.000Z
- end* : Enddate as IsoDate String: 2015-05-27T16:00:00.000Z
- rooms* : List of room numbers (roomid) separated by commas : 6,8,10
- lang : Language in the response as a string : en
Example 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
Example 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 at
http://www.disporoom.com/application/
The query returns the Captcha (PNG) as octet stream
The following parameters are supported (* required):
- apikey* : Access key as a string : umweltverein.b31726cb1e14c8d9
Example Request :
https://disporoom.com/application/api/captcha?apikey=umweltverein.b31726cb1e14c8d9
Form Post request at
http://www.disporoom.com/application/
The correct processing of the form data provides the reservation number generated.
The following parameters are supported (* required):
- apikey* : Access key as a string : umweltverein.b31726cb1e14c8d9
- room* : room id or room code (short name) as a string : 8 oder sh
- capcha* : Security check as string (captcha) : x67g3
- start* : Startdate als IsoDate String : 2015-05-26T12:00:00.000Z
- end* : Enddate als IsoDate String : 2015-05-27T16:00:00.000Z
- lastname* : Lastname of the person who creates the booking : Smith
- firstname* : Persons firstname : Walter
- email* : E-Mail address : walter.smith@disporoom.com
- street* : Street : Hauptstrasse 23
- city* : City : Boston
- zip* : Zip : 23445
- comment : Additional text for booking : My comment
- lang : Language for confirmation messages (default = de) : en
Example Form :
see source code of the demo page
Response Status Codes
In case of faulty or incomplete parameters or unknown URL you will receive a status code which can be programmatically analyzed, or displayed using the JavaScript Console of the browser. In response body is included possibly a more detailed error message.
Z.B.: Http Error 400 Bad Request
apikey: check format - API key wrong.
apikey: not found - for the given customer, there is no API key.
apikey: not allowed - the specified API key exists, but not allowed to call this funtion.
wrong ISO date param - Dateformat not ISO 8601 kompatibel
bad user data - Failed to process the data given. (To the specified e-mail address there already exist other information)
