04
API Design
GET/search?location=Lisbon&checkin=2026-06-03&checkout=2026-06-10&guests=4&price_max=200
Primary search. Returns {listings: [{id, title, price_per_night, total_price, photo_urls, location_approx, rating}], total_count, map_bbox}. Backed by Elasticsearch index pre-pruned for the date window.
GET/listings/{id}?checkin=X&checkout=Y&guests=N
Listing detail + authoritative price quote for the requested date window. Returns line-item breakdown: nightly × N, cleaning fee, service fee, taxes.
POST/reservations/quote
Lock in a price quote. Server returns {quote_id, expires_at (10 min), total}. Guest has 10 minutes to complete booking at this price. Protects against race on fee changes mid-checkout.
POST/reservations
Confirm booking. Body: {quote_id, payment_token, guest_message}. Idempotency-key required. Executes the booking saga; returns {reservation_id, status}.
GET/listings/{id}/calendar?start=2026-06&end=2026-09
Per-listing availability calendar. Returns array of (date, status, nightly_price). Used by guest detail view + host dashboard. Served from a read replica; stale by < 1 s.
POST/listings
Host creates or edits a listing. Inline validation; async indexing into Elasticsearch (< 60 s lag).
POST/listings/{id}/calendar
Host blocks dates / sets per-night prices. Writes to authoritative calendar store; invalidates search index entries for those dates.
POST/reservations/{id}/cancel
Cancel with policy check. Returns refund breakdown. Calendar re-opens; emits event to re-index search.