🔌 Sketch API Design

REST endpoints, message shapes, and data contracts for the notification system

https://api.chessboxing.events/v1
🏟️
Event Ingestion
Match events from venue systems
POST /events/match Ingest a match event → dedup → queue API Key
▶ Request Body
// Match event from venue scoring system { "event_id": uuid, *required — idempotency key "match_id": "match-mars-001", "event_type": "piece_captured" | "check" | "checkmate" | "punch_landed" | "ko" | "tko", "timestamp": "2026-02-11T14:30:00Z", "venue": "mars-arena-1", "data": { "player": "player-mars-001-a", // any player ID "piece": "queen", // chess events only "punch_type": "uppercut", // boxing events only "round": 3 }, "priority": "normal" | "high" | "critical" }
◀ 202 Accepted
{ "status": "queued", "event_id": "550e8400-...", "estimated_delivery_ms": 150 }
⚠ Error Responses
400 Invalid payload 401 Bad API key 409 Duplicate event 429 Rate limited
⬇ Redis SETNX dedup → RabbitMQ publish ⬇
👤
User Preferences
Notification channel & event subscriptions
GET /users/{user_id}/preferences Retrieve notification preferences JWT
◀ 200 OK
{ "user_id": "user-456", "notifications": { "web_push": true, "mobile_push": true, "email": false }, "events": { "piece_captured": true, "check": true, "checkmate": true, "punch_landed": false, "ko": true, "tko": true } }
PUT /users/{user_id}/preferences Update preferences → invalidates Redis cache JWT
▶ Request Body
{ "notifications": { "web_push": true, "mobile_push": true, "email": true }, "events": { "piece_captured": true, "punch_landed": true // ...partial update supported } }
◀ 200 OK
// Returns full updated preferences // Same shape as GET response
⚠ Error Responses
400 Invalid data 404 User not found
📱
Device Registration
FCM token management for push notifications
POST /devices/register Register FCM device token JWT
▶ Request Body
{ "user_id": "user-456", *required "platform": "ios" | "android" | "web", *required "token": "fcm_token_...", *required "app_version": "1.2.3" }
◀ 201 Created
{ "device_id": uuid, "user_id": "user-456", "platform": "ios", "registered_at": "2026-02-11T14:00:00Z" }
⚠ Error Responses
400 Invalid data 409 Already registered
DELETE /devices/{device_id} Unregister device (or auto-removed on FCM 400/404) JWT
◀ 204 No Content
// Empty response body on success
404 Device not found
💓
Health & Readiness
System status and dependency checks
GET /health Full health check with metrics Public
◀ 200 OK / 503 Unhealthy
{ "status": "healthy" | "degraded" | "unhealthy", "version": "1.0.0", "uptime_seconds": 86400, "dependencies": { "postgresql": "up", "redis": "up", "rabbitmq": "up" }, "metrics": { "queue_depth": { "web": 42, "ios": 18, "android": 31, "email": 5, "dlq": 0 }, "events_processed_last_minute": 1847, "active_workers": 16 } }
GET /health/ready K8s readiness probe (PostgreSQL, Redis, RabbitMQ) Public
◀ Response
200 All dependencies reachable 503 One or more dependencies down

📦 Internal Message Shapes

Data contracts between services via RabbitMQ queues

📨 NotificationPayload RabbitMQ
// API Gateway → Platform Worker Queues { "notification_id": uuid, "event_id": uuid, // trace to source "user_id": "user-456", "title": "♛ Queen Captured!", "body": "Elon captured Zuck's Queen in R3!", "platform": "web" | "ios" | "android" | "email", "priority": "normal" | "high" | "critical", "data": { "match_id": "match-mars-001", "deep_link": "/matches/match-mars-001/live", "event_type": "piece_captured" }, "created_at": "2026-02-11T14:30:00Z", "ttl_seconds": 300, "retry_count": 0, "max_retries": 3 }
📦 NotificationBatch FCM Multicast
// Worker → Firebase Cloud Messaging // Up to 500 tokens per multicast request { "batch_id": uuid, "platform": "ios", "device_tokens": [ "fcm_token_001", "fcm_token_002", // ...up to 500 ], "title": "♛ Queen Captured!", "body": "Elon captured Zuck's Queen!", "data": { ...metadata }, "priority": "high" }
✅ BatchDeliveryResult FCM Response
// Firebase → Worker (delivery receipt) { "batch_id": uuid, "success_count": 498, "failure_count": 2, "failed_tokens": [ { "device_token": "fcm_token_expired", "error_code": "NOT_FOUND", "should_retry": false, "should_remove_token": true } ], "duration_ms": 45 }
💀 DeadLetterEntry DLQ
// Failed notifications → Dead Letter Queue { "original_payload": { ...NotificationPayload }, "failure_reason": "max_retries_exceeded", "total_attempts": 3, "failed_at": "2026-02-11T14:30:05Z" }

🏷️ Enumerations

Shared type definitions across the system

EventType
  • piece_captured — Major piece taken
  • check — King in check
  • checkmate — Chess game over
  • punch_landed — Significant hit
  • ko — Knockout
  • tko — Technical knockout
Priority
  • normal — Standard delivery
  • high — Elevated (check)
  • critical — Immediate (KO, checkmate)
Platform
  • web — Browser push (FCM)
  • ios — iOS push (APNs/FCM)
  • android — Android push (FCM)
  • email — Email (SendGrid/SES)
DeliveryStatus
  • queued — In RabbitMQ queue
  • processing — Worker handling
  • sent — Sent to FCM/provider
  • delivered — Confirmed on device
  • failed — Moved to DLQ
  • expired — TTL exceeded
ChessPiece
  • pawn
  • knight
  • bishop
  • rook
  • queen
  • king

World ChessBoxing Championship — Notification System API Design

OpenAPI 3.1 · Protocol Buffers v3 · REST + Async Messaging

Marvin the Martian
"This technology and infrastructure is better than my Illudium Q-36 Explosive Space Modulator!" ✓ Marvin the Martian Approved