Skip to main content

​
Quick Start Guide

Get your Library Management API up and running in just a few minutes. This guide will walk you through the essential steps to start using the API.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Java 21 or later
  • Maven 3.6+
  • PostgreSQL 12+
  • Git

​
Quick Setup

1

Clone the repository

Clone the project from GitHub:
git clone https://github.com/Raven-Training/jc-java-training.git
cd jc-java-training
2

Create the database

Create a PostgreSQL database named book:
createdb book
Or using psql:
CREATE DATABASE book;
3

Set environment variables

Configure the required environment variables:
export db_url="jdbc:postgresql://localhost:5432/book"
export db_username="your_postgres_username"
export db_password="your_postgres_password"
export user_jwt="library-api-user"
export key_jwt="your-secret-jwt-key-at-least-256-bits-long"
The key_jwt must be at least 256 bits (32 characters) long for HMAC256 encryption.
4

Run the application

Start the application using Maven:
./mvnw spring-boot:run
The API will start on http://localhost:8081

​
Try Your First API Calls

Once the application is running, try these sample requests:
1

Register a new user

Create your first user account:
curl -X POST http://localhost:8081/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "birthDate": "1990-01-15",
    "username": "johndoe",
    "password": "SecurePass123",
    "email": "[email protected]"
  }'
Response:
{
  "username": "johndoe",
  "email": "[email protected]",
  "message": "User created successfully",
  "status": true
}
2

Login to get an access token

Authenticate with your credentials to receive a JWT token:
curl -X POST http://localhost:8081/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "SecurePass123"
  }'
Response:
{
  "username": "johndoe",
  "message": "User logged in successfully",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "status": true
}
Save the JWT token - you’ll need it for authenticated requests.
3

Make an authenticated request

Use your JWT token to fetch the list of books:
curl -X GET "http://localhost:8081/api/v1/books/findAll?page=0&size=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Replace YOUR_JWT_TOKEN with the token from step 2.
4

Create your first book

Add a new book to the library:
curl -X POST http://localhost:8081/api/v1/books/create \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Clean Code",
    "author": "Robert C. Martin",
    "isbn": "9780132350884",
    "gender": "Technology",
    "publisher": "Prentice Hall",
    "year": "2008",
    "pages": 464,
    "subtitle": "A Handbook of Agile Software Craftsmanship",
    "image": "https://example.com/clean-code.jpg"
  }'

​
Explore the API with Swagger

The API includes interactive Swagger documentation where you can explore and test all endpoints: 
http://localhost:8081/swagger-ui/index.html
Swagger provides a user-friendly interface to:
  • View all available endpoints
  • Test API requests directly from your browser
  • See request/response schemas
  • Authenticate using your JWT token

​
Next Steps

Installation Guide

Learn about detailed installation and configuration options

Authentication

Deep dive into JWT authentication and security

Books API

Explore the Books API endpoints

Users API

Explore the Users API endpoints

​
Troubleshooting

Verify your PostgreSQL is running and the connection details are correct:
psql -U your_username -d book -c "SELECT 1;"
Check that your environment variables are set correctly.
Change the server port in application.properties:
server.port=8082
Ensure your key_jwt environment variable is at least 256 bits (32 characters) long and matches between API calls.

Build docs developers (and LLMs) love

Get started for freeTalk to us