Tablez — API Catalog

All REST endpoints across Tablez services. Requests are routed through the API gateway (tablez-api-gateway) via YARP.

---

Gateway Routes

flowchart LR
    Client["Client"] --> GW["api.tablez.com<br/>(YARP Gateway)"]
    GW -->|"/api/reservations/**"| R["reservation-api"]
    GW -->|"/api/guests/**"| G["guest-api"]
    GW -->|"/api/restaurants/**"| REST["restaurant-api"]
    GW -->|"/api/ai/**"| AI["ai-api"]
    GW -->|"/health"| GW

---

Reservation Service

Base: /api/reservations

Method	Path	Description	Request	Response
POST	/api/reservations	Create reservation	CreateReservationCommand	201 + { id }
GET	/api/reservations/{id}	Get reservation	—	ReservationDocument
POST	/api/reservations/{id}/confirm	Confirm reservation	—	200
POST	/api/reservations/{id}/arrive	Mark guest arrived	—	200
POST	/api/reservations/{id}/seat	Seat guest at table	{ tableId }	200
POST	/api/reservations/{id}/complete	Complete visit	—	200
POST	/api/reservations/{id}/cancel	Cancel reservation	{ reason, cancelledBy }	200
POST	/api/reservations/{id}/no-show	Mark no-show	—	200
GET	/api/reservations/availability	Check available slots	?date=&partySize=	AvailabilitySlot[]
GET	/health	Health check	—	{ status: "healthy" }

CreateReservationCommand

{
  "guestId": "uuid",
  "partySize": 4,
  "dateTime": "2026-03-15T19:00:00Z",
  "channel": "Website"
}

ReservationDocument (response)

{
  "id": "uuid",
  "guestId": "uuid",
  "partySize": 4,
  "dateTime": "2026-03-15T19:00:00Z",
  "channel": "Website",
  "status": "Confirmed",
  "tableId": "uuid"
}

---

Guest Service

Base: /api/guests

Method	Path	Description	Request	Response
POST	/api/guests	Create guest profile	CreateGuestProfileCommand	201 + { id }
GET	/api/guests/{id}	Get guest profile	—	GuestDocument
PUT	/api/guests/{id}	Update guest profile	UpdateGuestProfileCommand	200
GET	/api/guests/search	Search by name/phone/email	?q=	GuestDocument[]
GET	/health	Health check	—	{ status: "healthy" }

CreateGuestProfileCommand

{
  "name": "Ola Nordmann",
  "phone": "+4799999999",
  "email": "ola@example.com"
}

GuestDocument (response)

{
  "id": "uuid",
  "name": "Ola Nordmann",
  "phone": "+4799999999",
  "email": "ola@example.com",
  "totalVisits": 12,
  "noShows": 0
}

---

Restaurant Service (planned)

Base: /api/restaurants

Method	Path	Description
GET	/api/restaurants/{id}	Get restaurant config
PUT	/api/restaurants/{id}	Update restaurant config
GET	/api/restaurants/{id}/tables	List tables
POST	/api/restaurants/{id}/tables	Add table
PUT	/api/restaurants/{id}/tables/{tableId}	Update table
GET	/api/restaurants/{id}/schedule	Get operating hours
PUT	/api/restaurants/{id}/schedule	Update operating hours
GET	/health	Health check

---

AI Service (planned)

Base: /api/ai

Method	Path	Description
POST	/api/ai/chat	Send message to AI agent
POST	/api/ai/phone/webhook	Inbound phone call webhook
GET	/api/ai/conversations/{id}	Get conversation history
GET	/health	Health check

Chat request

{
  "conversationId": "uuid",
  "message": "I'd like to book a table for 4 this Friday at 7pm",
  "channel": "Website",
  "guestId": "uuid (optional)"
}

Chat response

{
  "conversationId": "uuid",
  "message": "I found a table for 4 this Friday at 19:00. Shall I confirm the booking?",
  "actions": [
    { "type": "reservation_created", "reservationId": "uuid" }
  ]
}

---

Notification Service (planned)

Base: /api/notifications

Method	Path	Description
POST	/api/notifications/send	Send notification (internal)
GET	/api/notifications/templates	List notification templates
GET	/health	Health check

---

MCP Surface (planned)

External AI agents connect via MCP protocol. Same operations as REST, different transport.

Tool	Maps to
check_availability	GET /api/reservations/availability
create_reservation	POST /api/reservations
cancel_reservation	POST /api/reservations/{id}/cancel
get_guest_profile	GET /api/guests/{id}
get_restaurant_info	GET /api/restaurants/{id}

---

Common Patterns

All endpoints return: - 200 for successful GET/PUT - 201 with Location header for successful POST (create) - 404 when resource not found - 400 for validation errors - 409 for state machine violations (e.g., cancelling an already-completed reservation)

Authentication: JWT bearer tokens (to be implemented). Restaurant staff endpoints require auth. Public booking endpoints use rate limiting.

Versioning: URL-based (/api/v1/...) when breaking changes are needed. Not implemented yet — will add before first external consumer.