From 2b84ed0de87e0a65273f5ac22abfa9e5d228994e Mon Sep 17 00:00:00 2001
From: Cedric Hornberger <ceddi.hornberger@gmx.de>
Date: Sun, 10 May 2026 20:14:22 +0200
Subject: [PATCH] docs: write home and users endpoint sections

---
 docs/API.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 112 insertions(+), 2 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index c4ee4c8..b9df55d 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -87,11 +87,121 @@ No `Retry-After` header is currently returned. Clients should back off and retry
 
 ### 4.1 Home
 
-_TODO_
+#### `GET /`
+
+Health check. No authentication required.
+
+**Response:** `200 OK`
+```
+Welcome
+```
+
+---
 
 ### 4.2 Users
 
-_TODO_
+Base path: `/api/users`
+
+---
+
+#### `POST /api/users/createUser` — Register a user
+
+**Auth required:** No
+
+**Request body:**
+```json
+{
+  "username": "alice",
+  "googleId": "118400012345678901234"
+}
+```
+
+| Field | Type | Constraints |
+|-------|------|-------------|
+| `username` | String | Required. 3–30 chars. Pattern: `^[a-zA-Z0-9_.\-]+$` |
+| `googleId` | String | Required. Non-blank. Must match the JWT `sub` from Google. |
+
+**Success response:** `200 OK` — returns the created [AppUser](#appuser) object.
+
+**Error responses:**
+| Status | Condition |
+|--------|-----------|
+| 400 | Validation failure (field errors returned as `{"fieldName": "message"}`) |
+| 409 | `username` already taken |
+
+---
+
+#### `GET /api/users` — Get user by ID
+
+**Auth required:** Yes
+
+**Query params:**
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | Long | Yes | Database ID of the user |
+
+**Success response:** `200 OK` — returns [AppUser](#appuser).
+
+**Error responses:**
+| Status | Condition |
+|--------|-----------|
+| 404 | No user found for `id` |
+
+---
+
+#### `GET /api/users/byName` — Get user by username
+
+**Auth required:** No
+
+**Query params:**
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `username` | String | Yes | Exact username (case-sensitive) |
+
+**Success response:** `200 OK` — returns [AppUser](#appuser).
+
+**Error responses:**
+| Status | Condition |
+|--------|-----------|
+| 404 | No user found for `username` |
+
+---
+
+#### `GET /api/users/byGoogleId` — Get user by Google ID
+
+**Auth required:** Yes
+
+**Query params:**
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | String | Yes | Google `sub` claim |
+
+**Success response:** `200 OK` — returns [AppUser](#appuser).
+
+**Error responses:**
+| Status | Condition |
+|--------|-----------|
+| 404 | No user found for that Google ID |
+
+---
+
+#### `DELETE /api/users` — Delete a user
+
+**Auth required:** Yes
+
+**Query params:**
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | Long | Yes | Database ID of the user to delete |
+
+**Success response:** `200 OK` — returns the deleted [AppUser](#appuser).
+
+**Error responses:**
+| Status | Condition |
+|--------|-----------|
+| 404 | No user found for `id` |
+
+---
 
 ### 4.3 Expense Lists