Skip to main content
The BookMe API is a RESTful backend service for managing meeting room reservations at Hive Helsinki. It provides secure authentication via 42 OAuth, comprehensive reservation management, and integrates with Google Calendar for scheduling.

​
Base URL

http://localhost:8080
All API endpoints require HTTPS in production. The base URL will vary depending on your deployment environment.

​
API Endpoints

​
Authentication

MethodEndpointDescriptionAuth Required
GET/oauth/loginInitiate OAuth loginNo
GET/oauth/callbackOAuth callback handlerNo

​
Reservations

MethodEndpointDescriptionAuth Required
POST/api/v1/reservationsCreate a new reservationYes
GET/api/v1/reservationsGet unavailable time slotsYes
DELETE/api/v1/reservations/{id}Cancel a reservationYes

​
Health Check

MethodEndpointDescriptionAuth Required
GET/api/v1/healthHealth check endpointNo

​
Health Check

The health endpoint monitors the status of critical services including database, calendar, and email systems. 
curl http://localhost:8080/api/v1/health

​
Business Rules

​
Reservation Constraints

​
Time Validation

  • Cannot book past times
  • End time must be after start time
  • Bookings must be within school hours: 6:00 AM - 8:00 PM
  • Maximum duration:
    • Students: 4 hours
    • Staff: Unlimited
  • Date range queries cannot exceed 60 days
Reservations outside school hours (6:00 AM - 8:00 PM) will be rejected with a 400 Bad Request error.

​
Overlap Prevention

  • The system automatically checks for conflicting reservations
  • Returns 409 Conflict if a time slot is already booked

​
Authorization Rules

  • Students can only cancel their own reservations
  • Staff members can cancel any reservation
Unauthorized cancellation attempts return a 403 Forbidden error.

​
Privacy

Booking details are visible to:
  • The person who made the booking
  • Staff members
Other users only see time slots marked as “booked” without personal details.

​
Email Notifications

The system automatically sends email notifications for:
  • Booking Confirmation – Sent immediately after successful reservation
  • Cancellation Notice – Sent when a reservation is cancelled

​
Gmail SMTP Configuration

  1. Enable 2-Factor Authentication on your Google account
  2. Generate an App Password at myaccount.google.com/apppasswords
  3. Select Mail and your device
  4. Copy the generated 16-character password
  5. Use this password as:
SMTP_PASSWORD=your-gmail-app-password

​
Next Steps

Authentication Flow

Learn how OAuth authentication works

Rate Limiting

Understand API rate limits and quotas

Error Handling

Handle errors and validation issues

Endpoints

Explore all available endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us