diff --git a/docs/API.md b/docs/API.md index 8ba848b..67d531d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -477,7 +477,124 @@ Joins the caller to a shared expense list using an invite code. ## 5. Data Models -_TODO_ +### AppUser + +Returned by all `/api/users` endpoints. Sensitive fields (`googleId`, `createdAt`) are hidden from API responses via `@JsonIgnore`. + +```json +{ + "id": 1, + "username": "alice" +} +``` + +| Field | Type | Notes | +|-------|------|-------| +| `id` | Long | Auto-generated primary key | +| `username` | String | Unique. 3–30 chars. | + +--- + +### ExpenseList + +```json +{ + "id": 1, + "name": "Road Trip", + "inviteCode": "AB3X7Q", + "owner": { "id": 1, "username": "alice" }, + "sharedWith": { "id": 2, "username": "bob" }, + "xpenselyStandardCategories": { + "id": 1, + "categories": [ + { "id": 1, "name": "Food", "colorCode": "#FF5733" } + ] + }, + "customCategories": [], + "expenses": [] +} +``` + +| Field | Type | Notes | +|-------|------|-------| +| `id` | Long | Auto-generated primary key | +| `name` | String | Display name of the list | +| `inviteCode` | String \| null | 6-char code; `null` if not yet generated or expired | +| `owner` | AppUser | User who created the list | +| `sharedWith` | AppUser \| null | Second member of the list; `null` until an invite is accepted | +| `xpenselyStandardCategories` | XpenselyStandardCategories | Default category set assigned at creation | +| `customCategories` | XpenselyCustomCategory[] | User-defined categories, ordered A→Z | +| `expenses` | Expense[] | All expenses, ordered by date ASC then id ASC | + +> `inviteCodeExpiration` is hidden from API responses (`@JsonIgnore`). + +--- + +### Expense + +```json +{ + "id": 7, + "title": "Dinner", + "owner": { "id": 1, "username": "alice" }, + "amount": 42.50, + "personalUseAmount": 21.25, + "otherPersonAmount": 21.25, + "category": "Food", + "date": "2026-05-09" +} +``` + +| Field | Type | Notes | +|-------|------|-------| +| `id` | Long | Auto-generated | +| `title` | String | Description of the expense | +| `owner` | AppUser | Who paid | +| `amount` | Double | Total amount. Min 0.01. | +| `personalUseAmount` | Double \| null | Caller's share | +| `otherPersonAmount` | Double \| null | Other member's share | +| `category` | String | Category name (free text — must match a category on the list) | +| `date` | String (ISO-8601) | `YYYY-MM-DD` | + +> The `expenseList` back-reference is excluded via `@JsonBackReference` to prevent circular serialisation. + +--- + +### XpenselyStandardCategories + +A named group of standard categories assigned to every new expense list. + +```json +{ + "id": 1, + "categories": [ + { "id": 1, "name": "Food", "colorCode": "#FF5733" }, + { "id": 2, "name": "Transport", "colorCode": "#3498DB" } + ] +} +``` + +--- + +### XpenselyCustomCategory + +A user-defined category attached to a specific expense list. + +```json +{ + "id": 5, + "name": "Souvenirs", + "colorCode": "#9B59B6" +} +``` + +| Field | Type | Notes | +|-------|------|-------| +| `id` | Long | Auto-generated | +| `name` | String | Category label | +| `colorCode` | String | 7-char hex string e.g. `#RRGGBB` | + +> The `expenseList` back-reference is excluded via `@JsonBackReference`. ## 6. Error Handling