feat(hackathon): draft data table column & API Contract

2025-11-30 18:54:34 +07:00
parent 5faba43728
commit 1343404e01
8 changed files with 200 additions and 360 deletions
@@ -0,0 +1,58 @@
+# Hackathon Backoffice API Contract
+
+## GET /api/v1/dashboard
+
+### Purpose
+
+Single endpoint delivering aggregated metrics for the IMPHNEN x Kolosal.ai Hackathon dashboard.
+
+### Authentication & Authorization
+
+- Requires admin (backoffice) scope: e.g. `role=admin`
+- 401 if unauthenticated, 403 if authenticated but lacking required scope.
+
+### Examples
+
+```
+GET /api/v1/hackathon/dashboard
+```
+
+### Response Schema
+
+```jsonc
+{
+  "data": {
+    "total_participants": 1261,
+    "total_teams": 206,
+    "total_submissions": 0 // Total project submitted
+  }
+}
+```
+
+### Field Types
+
+| Path                      | Type    | Notes                 |
+| ------------------------- | ------- | --------------------- |
+| `data.total_participants` | integer | >= 0                  |
+| `data.total_teams`        | integer | >= 0                  |
+| `data.total_submissions`  | integer | <= `data.total_teams` |
+
+### Errors
+
+| Status | Code             | Message                       | Notes                 |
+| ------ | ---------------- | ----------------------------- | --------------------- |
+| 401    | `unauthorized`   | `authentication required`     | Missing/invalid token |
+| 403    | `forbidden`      | `insufficient permissions`    | Lacks required scope  |
+| 429    | `rate_limited`   | `too many dashboard requests` | Rate limiting         |
+| 500    | `internal_error` | `unexpected server error`     | Unhandled exception   |
+
+## Rate Limiting
+
+- Suggested: 30 requests / minute / admin user.
+- Return 429 with `Retry-After` header.
+
+---
+
+**Revision History**
+
+- v1.0.0 (2025-11-30): Initial contract drafted.