๐Ÿ”Œ 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
Marvin the Martian
"This technology and infrastructure is better than my Illudium Q-36 Explosive Space Modulator!" โœ“ Marvin the Martian Approved