From a55d1b324cea3a85e7e179ef45fb9e298532984e Mon Sep 17 00:00:00 2001
From: Florian <flo@meergans.org>
Date: Sat, 18 Oct 2025 19:58:25 +0200
Subject: [PATCH] Updated readme

---
 README.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 122 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 13b954e..f96674a 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,123 @@
-# backend-api
+# Device Token Management API
 
+A FastAPI-based service for managing device push notification tokens with secure storage, API key authentication, and Prometheus metrics.
+
+## Features
+
+- **Secure Token Storage**: Tokens are encrypted before storage and hashed for quick lookups
+- **API Key Authentication**: Protected endpoints using API key verification
+- **Platform Validation**: Ensures only valid platforms and tokens are registered
+- **Health Monitoring**: Built-in health check endpoint with database connectivity verification
+- **Metrics Collection**: Prometheus metrics endpoint for monitoring request patterns
+- **MySQL Connection Pooling**: Database connection management with automatic health checks
+
+## Prerequisites
+
+- Python 3.8+
+- MySQL database
+- Required Python packages (see Installation)
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+
+
+## Running the Application
+
+```bash
+python main.py
+```
+
+This starts two servers:
+- **Main API**: `http://0.0.0.0:8100`
+- **Metrics Server**: `http://0.0.0.0:9000`
+
+## API Endpoints
+
+### Health Check
+```
+GET /health
+```
+Returns the service health status and database connectivity.
+
+**Response:**
+```json
+{
+    "status": "ok",
+    "message": "Service is running"
+}
+```
+
+### Register Token
+```
+POST /register-token
+```
+
+Registers or updates a device token for push notifications.
+
+**Headers:**
+- `X-API-Key`: Your API key
+
+**Request Body:**
+```json
+{
+    "token": "device_push_token",
+    "platform": "ios|android|web",
+    "app_ver": "1.0.0",
+    "locale": "en_UK",
+    "topics": ["news", "updates"]
+}
+```
+
+**Response:**
+```json
+{
+    "status": "registered"
+}
+```
+
+### Unregister Token
+```
+POST /unregister-token
+```
+
+Marks a device token as expired.
+
+**Headers:**
+- `X-API-Key`: Your API key
+
+**Request Body:**
+```json
+{
+    "token": "device_push_token",
+    "platform": "ios|android|web",
+    "app_ver": "1.0.0"
+}
+```
+
+**Response:**
+```json
+{
+    "status": "unregistered"
+}
+```
+
+## Authentication
+
+All endpoints except `/health` require authentication via the `X-API-Key` header. API keys are verified against hashed values stored in the database.
+
+## Error Responses
+
+- `401 Unauthorized`: Invalid or missing API key
+- `403 Forbidden`: Invalid platform or token format
+- `500 Internal Server Error`: Database or server error
+
+## Monitoring
+
+Prometheus metrics are exposed on port 9000 and include:
+- HTTP request counters by method, path, and status code
+
+Access metrics at: `http://0.0.0.0:9000/metrics`
\ No newline at end of file