First version

2.backend-api.md

@@ -0,0 +1,161 @@
+
+# Backend API – Getting Started
+
+## 1. Project overview
+
+The `backend-api` is a small REST API responsible for receiving, storing and delivering notifications.
+
+It uses:
+- **FastAPI:** Python web framework for building REST APIs.
+- **Uvicorn:** Server used to run the FastAPI application.
+- **SQLite:** Lightweight database for storing notifications.
+- **Pydantic:** Data validation for incoming API requests (included with FastAPI).
+
+## 2. API endpoints
+
+The application requires two POST endpoints. POST is used when the application call changes something, GET when it just retrieves information.
+
+| Method | Endpoint | Description |
+|---|---|---|
+| POST | `/notifications` | Receive and store a notification. |
+| POST | `/notifications/deliver` | Retrieve pending notifications and mark them as delivered. |
+
+### Receiving notifications
+
+`POST /notifications`
+
+Accepts a JSON payload containing the notification information.
+
+Example request:
+
+```json
+{
+	"title": "New notification",
+	"body": "Something happened!",
+	"link": "https://example.com",
+	"timestamp": 1791626400
+}
+```
+
+The API validates the payload and saves it into the `notifications` database.
+
+Each notification should have a `delivered` flag, initially set to `false`.
+
+### Getting notifications
+
+`POST /notifications/deliver`
+
+This endpoint retrieves all notifications where `delivered = false`.
+
+The application should:
+1. Query the database for undelivered notifications.
+2. Set their `delivered` flag to `true`.
+3. Commit the database transaction.
+4. Return the retrieved notifications as JSON.
+
+Example response:
+
+```json
+[
+	{
+		"id": 1,
+		"title": "New notification",
+		"body": "Something happened!",
+		"link": "https://example.com",
+		"timestamp": 1791626400,
+		"delivered": true
+	}
+]
+```
+
+If there are no pending notifications, return an empty array.
+
+**Important:** The database update should happen before returning the notifications. This prevents the same notifications from being delivered again on subsequent requests.
+
+## 3. Database structure
+
+For the initial implementation, use SQLite.
+
+The database will be stored in a local file called `notifications.db`.
+
+The `notifications` table should contain:
+
+| Column | Type | Description |
+|---|---|---|
+| `id` | INTEGER | Unique notification identifier (primary key). |
+| `title` | TEXT | Notification title. |
+| `body` | TEXT | Notification content. |
+| `link` | TEXT | Optional URL associated with the notification. |
+| `timestamp` | INTEGER | Unix timestamp of the notification. |
+| `delivered` | BOOLEAN | Indicates whether the notification was delivered. |
+
+---
+
+# 4. Minimal working implementation
+
+The following implementation gives you a baseline for starting the server
+
+## requirements.txt
+
+```text
+fastapi
+uvicorn
+```
+
+## src/main.py
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from pydantic import BaseModel #use this to create the Notification class
+from db_module import initialize_database, get_database #Implement these yourself with SqLite3
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+	initialize_database()
+	yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+@app.post("/notifications")
+def receive_notification(notification: Notification):
+
+
+
+@app.post("/notifications/deliver")
+def deliver_notifications():
+
+```
+
+## 6. Run the application
+
+Make sure the virtual environment is activated and the dependencies are installed.
+
+Start the application from the project root:
+
+```bash
+uvicorn src.main:app --host 0.0.0.0 --port 8100 --reload
+```
+
+Explanation:
+
+| Argument | Description |
+|---|---|
+| `src.main:app` | Imports the FastAPI instance called `app` from `src/main.py`. |
+| `--host 0.0.0.0` | Makes the server accessible outside localhost. |
+| `--port 8100` | Port on which the API listens. |
+| `--reload` | Automatically restarts the server when source files change. |
+
+The `--reload` option should only be used during development.
+
+## 7. Test the application
+
+FastAPI automatically generates interactive API documentation.
+
+Open:
+
+http://localhost:8100/docs
+
+You can use the Swagger UI to execute both POST endpoints without installing additional tools.