XpenselyServer/docs/API.md

# Xpensely Server — API Reference

> Last updated: 2026-05-09 · Branch: `feature/security-hardening`

## Table of Contents
1. [Overview](#1-overview)
2. [Authentication](#2-authentication)
3. [Rate Limiting](#3-rate-limiting)
4. [Endpoints](#4-endpoints)
   - 4.1 [Home](#41-home)
   - 4.2 [Users](#42-users)
   - 4.3 [Expense Lists](#43-expense-lists)
5. [Data Models](#5-data-models)
6. [Error Handling](#6-error-handling)
7. [Recent Changes — `feature/security-hardening`](#7-recent-changes)

---

## 1. Overview

Xpensely Server is a Spring Boot REST API that manages shared expense lists for pairs of users. It uses Google OAuth2 JWT tokens for authentication. All protected endpoints require a valid Bearer token in the `Authorization` header.

**Base URL (local dev):** `http://localhost:8080`

**Content-Type:** `application/json` for all request and response bodies.

**Public endpoints (no auth required):**
| Method | Path | Description |
|--------|------|-------------|
| GET | `/` | Health check — returns `"Welcome"` |
| POST | `/api/users/createUser` | Register a new user |
| GET | `/api/users/byName` | Look up a user by username |

All other endpoints require authentication (see [Section 2](#2-authentication)).

## 2. Authentication

_TODO_

## 3. Rate Limiting

_TODO_

## 4. Endpoints

### 4.1 Home

_TODO_

### 4.2 Users

_TODO_

### 4.3 Expense Lists

_TODO_

## 5. Data Models

_TODO_

## 6. Error Handling

_TODO_

## 7. Recent Changes — `feature/security-hardening`

_TODO_