Book a room every week

Requested by: Marco (Product, Workplace tools) · Priority: Medium · Target: next sprint · Component: Booking API

Goal

From the October office survey, the most common complaint after "can't book right after another meeting" was weekly meetings. Quotes from the free-text answers:

"I book our Tuesday standup by hand every week. Last month I forgot week 3 and somebody else took Orion, so we met in the corridor." (Engineering)

"Retro is the same room, same time, every second week. I send twelve requests and about once a quarter one of them bounces because of a clash and I only notice when we turn up." (Design)

Teams with weekly standups, 1:1s and retros want to book a room for the next few weeks in one go, as one series, and to see and cancel that series in one step. The important part is that a series is all or nothing: nobody should end up with a series that has holes in it because one week was already taken.

The API change below is what the booking screens and the calendar add-in will call once it exists.

Requirements

1. POST /bookings accepts an optional field repeat_weekly: the number of additional weekly occurrences, an integer from 1 to 12.
   • "repeat_weekly": 3 books the requested slot plus the same room and time 7, 14 and 21 days later, so 4 bookings in total.
   • When the field is missing or null, the request behaves exactly as it does today (one booking).
   • Any other value (0, negative, more than 12) is rejected with 422.
2. All bookings created by one request form a series and share a series_id. Every booking returned by the API (POST /bookings, GET /bookings/{id}, ...) has a series_id field: the series identifier, or null for a one-off booking. A successful POST with repeat_weekly returns 201 and the first booking of the series.
3. Occurrences keep the same room, title, organizer and local start/end time, and must land on the right calendar dates across month and year ends (e.g. 2026-12-29 → 2027-01-05).
4. All or nothing. If any occurrence would clash with an existing booking in that room (same overlap rules as single bookings today), nothing at all is booked and the API responds 409 with this body, listing every clashing date (YYYY-MM-DD, earliest first):

   {"detail": "Room already booked", "conflicting_dates": ["2026-11-17", "2026-12-01"]}
   

   A single booking that clashes keeps today's response: 409 {"detail": "Room already booked"}.
5. New endpoints:
   • GET /series/{series_id} → 200 with the list of the series' bookings, earliest first.
   • DELETE /series/{series_id} → 204; cancels every booking of the series.
   • Both return 404 for a series that does not exist (including one that was already cancelled).
6. Existing endpoints keep working as they do today. DELETE /bookings/{id} on one occurrence cancels only that week; the rest of the series stays booked.

Acceptance

• Booking Orion every Tuesday 09:00–10:00 starting 2026-11-03 with repeat_weekly: 3 gives bookings on 11-03, 11-10, 11-17 and 11-24 (and not on 12-01), all with the same series_id; the room shows busy at 09:00 on each of those days.
• repeat_weekly of 0, 13 or -1 → 422, and nothing is booked.
• If someone already has Orion on 2026-11-17 09:30–10:30, the request above → 409 with "conflicting_dates": ["2026-11-17"], and Orion is still free on 11-03, 11-10 and 11-24.
• A series starting 2026-12-22 lands on 12-22, 12-29, 2027-01-05 and 2027-01-12.
• GET /series/{id} lists the occurrences; DELETE /series/{id} → 204, after which every occurrence is gone (GET /bookings/{id} → 404) and the slots can be booked again; a second DELETE → 404.
• Single bookings work exactly as before and show "series_id": null.