WP-002 Health & Wellness Intermediate

Appointment Booking API Design

Design the database schema and REST API for a health-tech booking system.

1

The Scenario

You are a junior full-stack engineer at Medbook, a health-tech SaaS that helps independent practitioners — physiotherapists, nutritionists, therapists, and GPs — manage their practice online. Medbook currently lets practitioners set up a profile and accept direct messages from patients, but there is no structured appointment booking system. The product team has just signed off on the next major feature: a patient-facing appointment booking flow. Before any code is written, your tech lead Priya wants a design document — a clear API contract, a database schema, and a written rationale — so the team can review and align before sprint planning.

2

The Task

Produce a design document (not working code) that defines the database schema, REST API endpoints, and engineering rationale for the appointment booking feature. Your document will be reviewed by a Senior Engineer in a simulated pre-sprint design review.

3

Requirements

3A

Data Model

  • Design a database schema that can store practitioners, patients, availability slots, and appointments.
  • Each availability slot must belong to a single practitioner and have a defined start time, end time, and status (available / booked).
  • Each appointment must link a patient to a specific availability slot and record the booking timestamp.
  • The schema must prevent a single slot from being booked by more than one patient.
  • Include a cancellation mechanism that makes the slot available again when an appointment is cancelled.
3B

REST API Endpoints

  • Practitioners must be able to create, update, and delete their availability slots.
  • Patients must be able to view available slots for a specific practitioner, filtered by date.
  • Patients must be able to book an available slot, which transitions the slot to 'booked'.
  • Either the patient or practitioner must be able to cancel a booking.
  • A patient must be able to view all of their upcoming appointments.
3C

Error & Edge Cases

  • Concurrent booking: explain how you prevent two patients booking the same slot simultaneously.
  • Past slot booking: address what happens if a patient attempts to book a slot whose start time has already passed.
  • Cancellation window: define and document a rule for how late a booking can be cancelled.
4

Constraints

  • A design document, not working code. Pseudocode is acceptable where helpful.
  • Must extend the existing Medbook schema — do not redesign the users or practitioners tables.
  • Use standard REST conventions (HTTP methods, status codes, JSON responses).
  • Database-agnostic schema (PostgreSQL or MySQL compatible).
5

Existing System Context

Existing tables to extend:
users(id, email, name, role, created_at)
practitioners(id, user_id FK, specialty, bio, created_at)
Your design must add new tables alongside these — do not alter the existing ones.

6

What to Submit

  • Section 1 — Executive Summary (1 paragraph)
  • Section 2 — Database Schema (table definitions + ERD sketch)
  • Section 3 — API Endpoint Reference (method, path, request/response shapes)
  • Section 4 — Edge Case Handling (concurrency, past slots, cancellation window)
  • Section 5 — Trade-offs & Assumptions (what you chose and why)
7

Hints

Two non-prescriptive hints. Read only if you're stuck — don't skip the thinking.

Hint 1

Concurrent booking is the crux of this problem. Think about what database-level guarantee prevents two simultaneous transactions from each seeing the slot as 'available'.

Hint 2

The cancellation window is a policy decision, not a technical one. Define it clearly, then build the API constraint around it.

Wooble  ·  Project #WP-002  ·  Appointment Booking API Design  ·  Health & Wellness Track  ·  v1.0