Room Booking

This application allows you to

1. create an event in a room booking calendar via a REST API.
2. delete an event in a room booking calendar via a REST API.
3. clear overlapping and canceled events in a room booking calendar via a REST API.

Setup

If you see this page, the application is already running.

You will have to create users, API keys and calendars via admin interface.

Usage

A full documentation of the API is available at /api/docs/.

Authentication is done via a Bearer token in the Authorization header.

Create an event

To create an event, you need to send a POST request to /api/{calendar}/events/ with the following JSON payload:

{
  "name": "Event Title",
  "start": "2025-01-02T12:00:00",
  "end": "2025-01-02T13:00:00"
}

Curl example:

 curl -s \
   -H "Authorization: Bearer secrettoken" \
   -H "Content-Type: application/json" \
   -d "{\"name\": \"Test-Event\", \"start\": \"$(date --iso-8601=minutes)\", \"end\": \"$(date --iso-8601=minutes -d '+2 hours')\"}" \
   localhost:8000/api/test-kalender/event

The response will contain the event ID:

{"id": "4zx3QAFzoxV3vaZSKGaH2S"}

Delete an event

To delete an event, you need to send a DELETE request to /api/{calendar}/events/{event_id}.

Curl example:

curl -s -X DELETE \
  -H "Authorization: Bearer secrettoken" \
  -H "Content-Type: application/json" \
  localhost:8000/api/test-kalender/event/4zx3QAFzoxV3vaZSKGaH2S

The response will be empty but the status code will be 204.

Clear overlapping and canceled events

To clear overlapping and canceled events, you need to send a DELETE request to /api/clear-bookings.

The following parameters can be passed as query parameters:

• calendar: The calendar to clear overlapping events from. If not specified, all calendars of the user will be cleared.
• test: If set to 1 or ok, the API will not delete any events but only return what would be deleted.

Curl example:

curl -s -X DELETE \
  -H "Authorization: Bearer secrettoken" \
  localhost:8000/api/clear-bookings?calendar=meeting-room-1&test=on" | jq "."

The response will contain a list of events that would be deleted:

{
  "deleted_cancelled_events": [],
  "deleted_overlapping_events": [
    {
      "event": {
        "uid": "abeda082-2a4b-48a7-a92a-ba24575622ae",
        "name": "Fundraising Weekly",
        "start": "2025-07-14T00:00:00+02:00",
        "end": "2025-07-19T00:00:00+02:00",
        "created": "2025-07-09T15:11:19+02:00",
        "organizer": "head-of-fundraising@my-awesome.org"
      },
      "overlaps_with": {
        "uid": "2051008d-6ce2-4489-b7d9-38d164c5e66e",
        "name": "Finance Monthly",
        "start": "2025-07-15T10:00:00+02:00",
        "end": "2025-07-15T12:00:00+02:00",
        "created": "2025-01-14T08:33:20+01:00",
        "organizer": "head-of-finance@my-awesome.org"
      },
      "calendar": "meeting-room-1"
    }
  ],
  "cancelled_overlapping_recurring_events": [
    {
      "event": {
        "uid": "be6d2d42-513b-45ca-bb43-663e2a10a1d7",
        "name": "Job Interviews",
        "start": "2025-07-14T14:00:00+02:00",
        "end": "2025-07-14T15:00:00+02:00",
        "created": "2025-06-30T12:04:14+02:00",
        "organizer": "head-of-hr@my-awesome.org"
      },
      "overlaps_with": {
        "uid": "f2b7b703-dfba-4ae7-a0e9-bf0e7637c7e4",
        "name": "Workers Council Meeting",
        "start": "2025-07-14T14:00:00+02:00",
        "end": "2025-07-14T15:00:00+02:00",
        "created": "2025-02-10T12:33:39+01:00",
        "organizer": "workers-council@my-awesome.org"
      },
      "calendar": "meeting-room-2"
    }
  ],
  "ignored_overlapping_events": [],
  "test_mode": true
}

Email Notifications

The organizer of the events will be notified via email about the deletion of their event if an email template is configured for the calendar.

The following environment variables can be set to configure the application:

• SMTP_EMAIL - The email address to use as the sender for notification emails.
• SMTP_PASSWORD - The password for the SMTP email account.
• SMTP_SERVER - The SMTP server to use for sending emails.
• SMTP_USER_NAME - The username for the SMTP email account. If not set, the SMTP_EMAIL will be used as the username.
• SMTP_SENDER_NAME - The name to use as the sender for notification emails.
• SMTP_BCC - A comma-separated list of email addresses to BCC on notification emails.
• SMTP_STARTTLS - Whether to use STARTTLS for the SMTP connection. Defaults to False, so SSL is used instead.
• SMTP_PORT - The port to use for the SMTP connection. Defaults to 465 for SSL and 587 for STARTTLS.

Email templates can be configured in the Django Admin interface. Jinja2 syntax is used for the templates. The following variables are available in the templates:

• name - The name of the event
• start - The start time (datetime) of the event
• end - The end time (datetime) of the event
• created - The datetime the event was created
• is_deleted - Whether the event was deleted
• is_cancelled - Whether the event was cancelled
• is_recurring - Whether the event is recurring
• is_priorized - Whether the event is prioritized
• is_deprioritized - Whether the event is deprioritized in favor of another event
• organizer - The organizer of the event
• overlap_events - A list of overlap events, each containing:
  • name - The name of the overlap event
  • start - The start time (datetime) of the overlap event
  • end - The end time (datetime) of the overlap event
  • created - The datetime the overlap event was created
  • organizer - The organizer of the overlap event
  • is_priorized - Whether the overlap event is prioritized
• calendar_name - The name of the calendar