Skip to main content

​
Welcome to the Library Management API

The Library Management API is a comprehensive REST API for managing books, users, and their collections. Built with Spring Boot, this API provides secure endpoints for creating, reading, updating, and deleting resources.

Base URL

http://localhost:8081
Development server for local testing

API Version

/api/v1
All endpoints are versioned under v1

​
API Overview

The API provides three main endpoint categories:

Authentication

User registration and login endpoints

Books

Complete CRUD operations for book management

Users

User management and book collection operations

​
API Versioning

All API endpoints are versioned to ensure backward compatibility. The current version is v1, and all endpoints are prefixed with /api/v1.
Endpoint Structure: http://localhost:8081/api/v1/{resource}Example: http://localhost:8081/api/v1/books/findAll

​
HTTP Methods

The API follows RESTful conventions and uses standard HTTP methods:
MethodUsageDescription
GETRead operationsRetrieve resources or lists of resources
POSTCreate operationsCreate new resources or perform authentication
PUTUpdate operationsUpdate existing resources
DELETEDelete operationsRemove resources from the system

​
Authentication

The API uses JWT (JSON Web Token) authentication to secure endpoints. Most endpoints require a valid JWT token in the request header.

​
Authentication Flow

  1. Register: Create a new user account via /api/v1/auth/register
  2. Login: Authenticate and receive a JWT token via /api/v1/auth/login
  3. Use Token: Include the token in subsequent requests

​
Token Format

Include the JWT token in the Authorization header using the Bearer scheme: 
Authorization: Bearer <your-jwt-token>
The token is returned in the response after successful login or registration.

​
Public Endpoints

The following endpoints do NOT require authentication:
  • POST /api/v1/auth/login - User login
  • POST /api/v1/auth/register - User registration
  • All Swagger UI endpoints (/swagger-ui/**, /v3/api-docs/**)

​
Protected Endpoints

All other endpoints require a valid JWT token in the Authorization header:
  • All /api/v1/books/** endpoints (except public ones)
  • All /api/v1/users/** endpoints
Security Scheme: HTTP Bearer authentication with JWT formatHeader: AuthorizationScheme: bearer

​
Response Formats

​
Success Responses

Successful requests return JSON responses with appropriate HTTP status codes:
  • 200 OK: Successful GET, PUT, or DELETE operation
  • 201 Created: Successful POST operation (resource created)

​
Error Responses

Error responses include detailed information about what went wrong: 
{
  "timestamp": "2025-08-05T10:30:00",
  "status": 404,
  "error": "Not Found",
  "message": "Book not found with id: 123e4567-e89b-12d3-a456-426614174000",
  "path": "/api/v1/books/findById/123e4567-e89b-12d3-a456-426614174000"
}

​
Common HTTP Status Codes

CodeMeaningDescription
200OKRequest succeeded
201CreatedResource successfully created
400Bad RequestInvalid request parameters or body
401UnauthorizedMissing or invalid authentication token
404Not FoundRequested resource not found
409ConflictResource already exists (e.g., duplicate email)
500Internal Server ErrorServer-side error occurred

​
Pagination

List endpoints (findAll) support pagination with the following query parameters:
ParameterTypeDefaultDescription
pageinteger0Page number (0-indexed)
sizeinteger10Number of items per page

​
Pagination Response Format

{
  "content": [...],
  "numberOfElements": 10,
  "size": 10,
  "offset": 0,
  "totalPages": 5,
  "totalElements": 50,
  "previousPage": null,
  "currentPage": 1,
  "nextPage": 2
}
Pages are 0-indexed in the API but displayed as 1-indexed in the response.

​
Data Format

​
UUID Identifiers

All resources use UUID (Universally Unique Identifier) format for IDs: 
123e4567-e89b-12d3-a456-426614174000

​
Date/Time Format

All timestamps follow the ISO 8601 format: 
2025-08-05T10:30:00Z

​
Environment Configuration

The API supports multiple deployment environments:

Development Server

URL: http://localhost:8081For local development and testing

Production Server

URL: http://books:8081For production deployment

​
Next Steps

Try Swagger UI

Interactive API documentation and testing

Authentication Guide

Learn how to authenticate with the API

Build docs developers (and LLMs) love

Get started for freeTalk to us