API Reference

Base path: /api (unversioned — see the specification’s decision log for why). Every endpoint except the ones tagged public requires Authorization: Bearer <Keycloak JWT>. For live, try-it-out request/response schemas, run the stack and open http://localhost:9080/openapi/ui/.

public no auth required user any authenticated user admin admin role required

Health

Method & path	Access	Notes
`GET /health`	public	Liveness check

Auth

Method & path	Access	Notes
`POST /auth/login`	user	Validates the caller’s token and returns their local profile
`GET /auth/validate`	user	Token validity check
`GET /auth/me`	user	Current user’s profile

Tokens themselves are issued by Keycloak, not this API — see Architecture.

Users

Method & path	Access	Notes
`POST /users`	user	Self-service profile sync (own `keycloakId` only, `role` forced to `USER`) or admin-created account (any role)
`GET /users`	admin	List all users
`GET /users/{id}`	admin	Look up a user
`GET /users/me`	user	Current user’s own record
`PUT /users/{id}`	admin	Update a user, including role reassignment
`DELETE /users/{id}`	admin	Remove a user

Books

Method & path	Access	Notes
`GET /books`	public	List/filter (`genre`, `availableOnly`)
`GET /books/{id}`	public	Single book
`GET /books/search?q=`	public	Title/author search
`GET /books/available`	public	Books with copies currently available
`POST /books`	admin	Create a book
`PUT /books/{id}`	admin	Update a book
`DELETE /books/{id}`	admin	Remove a book
`POST /books/bulk-upload`	admin	CSV bulk import
`GET /books/bulk-upload/template`	admin	Download the expected CSV shape

Queue (registration, borrow, return)

Method & path	Access	Notes
`POST /queues`	user	Submit a `BOOK_BORROW` or `BOOK_RETURN` request; blocked with `403` if the caller’s account is not yet approved
`GET /queues?status=&type=`	admin	List/filter all queue items
`GET /queues/{id}`	admin	Look up a queue item
`GET /queues/my`	user	Current user’s own queue items
`PATCH /queues/{id}/status`	admin	Approve or reject — drives the inventory/registration side effects in Business Rules
`DELETE /queues/{id}`	admin	Remove a queue item

Reservations

Method & path	Access	Notes
`POST /reservations`	user	Reserve an unavailable book
`GET /reservations`	admin	List all reservations
`GET /reservations/my`	user	Current user’s own reservations
`DELETE /reservations/{id}`	user	Cancel — own reservation, or any reservation as admin
`POST /reservations/{id}/fulfill`	admin	Mark fulfilled once the patron checks the book out

Overdue tracking

Method & path	Access	Notes
`GET /overdue`	admin	All overdue items
`GET /overdue/my`	user	Current user’s overdue items
`GET /overdue/stats`	admin	Aggregate overdue statistics

Email configuration

Method & path	Access	Notes
`POST /email/config`	admin	Create an SMTP configuration
`GET /email/config`	admin	List configurations (password never included)
`GET /email/config/active`	admin	Currently active configuration
`PUT /email/config/{id}`	admin	Update — omitting `password` preserves the existing one
`DELETE /email/config/{id}`	admin	Remove a configuration
`POST /email/config/{id}/activate`	admin	Make this the active configuration
`POST /email/config/test`	admin	Send a test email

Reports

Method & path	Access	Notes
`GET /reports/book-popularity?limit=`	admin	Most-borrowed books
`GET /reports/borrowing-trends?days=`	admin	Borrow/return volume over time
`GET /reports/user-activity?limit=`	admin	Most active users
`GET /reports/statistics`	admin	Library-wide counters
`GET /reports/author-distribution`	admin	Catalog breakdown by author

Reports return JSON only (no PDF export) — see the specification’s decision log for why.