API Documentation Complete REST API overview — base URL, authentication, dual-token system, request/response format, error codes, and endpoint index.
The SLMS backend exposes a RESTful API for all library operations. This page provides the complete overview; individual endpoint groups are documented in detail on their own pages.
http://localhost:5000/api/v1 All endpoints are prefixed with /api/v1/ for versioning.
SLMS uses a dual-token architecture with short-lived access tokens and long-lived refresh tokens:
Token Lifetime Purpose Access Token 15 minutes JWT sent in Authorization header for API access Refresh Token 7 days Opaque token used to obtain new access tokens
All protected endpoints require a JWT Bearer token in the Authorization header:
Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... When the access token expires, exchange the refresh token for a new access token:
POST /api/v1/auth/refresh Content-Type : application/json { "refreshToken" : "a1b2c3d4e5f6..." } Login → Access Token (15min) + Refresh Token (7 days) │ ├─ Access token expires │ └─ POST /auth/refresh → New Access Token │ └─ Logout └─ Both tokens blacklisted On logout, both the access and refresh tokens are added to the BlacklistedToken collection. The auth middleware checks the blacklist on every request. Blacklisted tokens are automatically purged by MongoDB's TTL index after their natural expiry.
Scope Window Max Requests Endpoints Auth routes 1 minute 5 per IP /auth/setup, /auth/login, /auth/refreshUser creation 1 minute 5 per IP POST /usersGlobal API 15 minutes 100 per IP All /api/ routes (in src/app.js)
Content-Type: application/jsonBody: JSON payloads for POST, PUT, and PATCH requestsURL Parameters: Path params (:id) and query strings (?search=term)
{ "books" : [ ... ], "accessToken" : "eyJ..." , "refreshToken" : "a1b2..." , "user" : { ... } } Responses use domain-specific keys (e.g., books, users, transaction) rather than a generic data wrapper.
{ "error" : "Human-readable error message" } Code Meaning When Used 200OK Successful GET, PUT, PATCH 201Created Successful POST (resource created) 400Bad Request Invalid input or business rule violation 401Unauthorized Missing, invalid, or expired JWT token 403Forbidden Insufficient role permissions 404Not Found Resource doesn't exist 429Too Many Requests Rate limit exceeded 500Internal Server Error Unhandled server error
Method Endpoint Auth Description POST/auth/setup— Create initial Super Admin POST/auth/login— Login and get dual tokens POST/auth/refresh— Refresh access token POST/auth/logout— Logout (blacklist tokens) GET/auth/me✅ Get current user profile
→ Detailed Auth Endpoints
Method Endpoint Auth Description GET/usersAdmin, Librarian List all users POST/usersAdmin Create user GET/users/me✅ Get own profile PATCH/users/me✅ Update own profile GET/users/:idAdmin, Librarian Get user by ID PATCH/users/:idAdmin, Librarian Update user
→ Detailed Users Endpoints
Method Endpoint Auth Description GET/books/categories✅ List all categories GET/books✅ List all books GET/books/:id✅ Get book by ID POST/booksAdmin, Librarian Create book PATCH/books/:idAdmin, Librarian Update book DELETE/books/:idAdmin, Librarian Delete book POST/books/:id/copiesAdmin, Librarian Add physical copy
→ Detailed Books Endpoints
Method Endpoint Auth Description POST/circulation/issueAdmin, Librarian Issue book POST/circulation/returnAdmin, Librarian Return book GET/circulation/history✅ Get borrowing history GET/circulation/activeAdmin, Librarian List active loans
→ Detailed Circulation Endpoints
Method Endpoint Auth Description GET/fines✅ List fines POST/fines/:id/payAdmin, Librarian Pay/resolve fine
→ Detailed Fines Endpoints
Method Endpoint Auth Description GET/dashboard/stats✅ Get aggregate statistics GET/dashboard/analytics✅ Get trend analytics data
→ Detailed Dashboard Endpoints
Method Endpoint Auth Description POST/reservations✅ Create a reservation GET/reservations/me✅ List own reservations POST/reservations/:id/cancel✅ Cancel own reservation GET/reservationsAdmin, Librarian List all reservations POST/reservations/:id/fulfillAdmin, Librarian Fulfill reservation
→ Detailed Reservations Endpoints
Method Endpoint Auth Description GET/notifications✅ Get own notifications PUT/notifications/mark-all-read✅ Mark all as read PUT/notifications/:id/read✅ Mark single as read
→ Detailed Notifications Endpoints
Method Endpoint Auth Description GET/reports/circulationAdmin, Librarian Download circulation CSV GET/reports/finesAdmin, Librarian Download fines CSV
→ Detailed Reports Endpoints
Method Endpoint Auth Description GET/auditAdmin Get audit logs
→ Detailed Audit Endpoints
Method Endpoint Auth Description GET/configAdmin List all configs PATCH/config/:idAdmin Update config value
→ Detailed System Config Endpoints
Method Endpoint Auth Description GET/health— Server health status
curl http://localhost:5000/health # { "status": "ok", "message": "SLMS API is running" }