Sign inSign up

archety/books-api-in-memory

By archety

•Updated 6 months ago

Spring Boot books REST API for learning, in-memory, Docker & Kubernetes ready

Image
Languages & frameworks
0

281

archety/books-api-in-memory repository overview

⁠Book Manager API

A simple Spring Boot REST API designed for Docker and Kubernetes labs.

This project provides a complete in-memory Book Management API with sample data loaded at startup.
The main goal is to let students:

  • pull a Docker image
  • run the container locally
  • push and pull images from a registry
  • deploy the application to Kubernetes
  • test REST endpoints
  • work with probes and service exposure

⁠Project goals

This project is intentionally simple and focuses on:

  • Spring Boot REST APIs
  • containerization with Docker
  • image distribution through a registry
  • deployment on Kubernetes
  • testing endpoints with sample in-memory data

There is no external database.
All book data is stored in memory, so every restart resets the dataset.

⁠Tech stack

  • Java 17
  • Spring Boot 3
  • Spring Web
  • Spring Boot Actuator
  • Spring Validation
  • Maven
  • Docker
  • Kubernetes

⁠Project structure

book-manager-api/
|-- pom.xml
|-- Dockerfile
|-- .dockerignore
|-- k8s/
|   |-- deployment.yaml
|   `-- service.yaml
`-- src/
    `-- main/
        |-- java/
        |   `-- dev/archety/bookmanager/
        |       |-- Img02BmsApplication.java
        |       |-- config/
        |       |   `-- DataSeeder.java
        |       |-- controller/
        |       |   |-- BookController.java
        |       |   `-- HomeController.java
        |       |-- dto/
        |       |-- exception/
        |       |-- model/
        |       |-- repository/
        |       `-- service/
        `-- resources/
            `-- application.properties

⁠Features

  • Full CRUD for books
  • Search books by genre and status
  • Sample data loaded automatically at startup
  • In-memory repository
  • Health endpoint for Kubernetes probes
  • Version endpoint for rollout verification
  • Ready-to-use Dockerfile
  • Ready-to-use Kubernetes manifests

⁠YouTube channel

Educational content, labs, and developer-focused videos by Giovanni Pace:

https://www.youtube.com/@archetydev⁠

⁠Base URL

When running locally:

http://localhost:8081

Base API path:

/api/books

⁠API Endpoints

⁠1. Get all books

Endpoint

GET /api/books

Description
Returns the full list of books currently stored in memory.

Example request

curl http://localhost:8081/api/books

Example response

[
  {
    "id": 1,
    "title": "The Hobbit",
    "author": "J.R.R. Tolkien",
    "isbn": "978-0261103344",
    "genre": "Fantasy",
    "pages": 310,
    "status": "AVAILABLE",
    "createdAt": "2026-04-13T14:00:00"
  },
  {
    "id": 2,
    "title": "Dune",
    "author": "Frank Herbert",
    "isbn": "978-0441172719",
    "genre": "Science Fiction",
    "pages": 688,
    "status": "BORROWED",
    "createdAt": "2026-04-13T14:00:00"
  }
]

⁠2. Get book by ID

Endpoint

GET /api/books/{id}

Description
Returns a single book by ID.

Example request

curl http://localhost:8081/api/books/1

Example response

{
  "id": 1,
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien",
  "isbn": "978-0261103344",
  "genre": "Fantasy",
  "pages": 310,
  "status": "AVAILABLE",
  "createdAt": "2026-04-13T14:00:00"
}

Example not found response

{
  "timestamp": "2026-04-13T14:15:00",
  "status": 404,
  "error": "Not Found",
  "message": "Book with id 99 not found"
}

⁠3. Create a new book

Endpoint

POST /api/books

Description
Creates a new book in memory.

Example request body

{
  "title": "Refactoring",
  "author": "Martin Fowler",
  "isbn": "978-0134757599",
  "genre": "Programming",
  "pages": 448,
  "status": "AVAILABLE"
}

Example request

curl -X POST http://localhost:8081/api/books \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refactoring",
    "author": "Martin Fowler",
    "isbn": "978-0134757599",
    "genre": "Programming",
    "pages": 448,
    "status": "AVAILABLE"
  }'

Example response

{
  "id": 11,
  "title": "Refactoring",
  "author": "Martin Fowler",
  "isbn": "978-0134757599",
  "genre": "Programming",
  "pages": 448,
  "status": "AVAILABLE",
  "createdAt": "2026-04-13T14:20:00"
}

⁠4. Update a book

Endpoint

PUT /api/books/{id}

Description
Replaces the full book resource.

Example request body

{
  "title": "Refactoring",
  "author": "Martin Fowler",
  "isbn": "978-0134757599",
  "genre": "Software Engineering",
  "pages": 455,
  "status": "RESERVED"
}

Example request

curl -X PUT http://localhost:8081/api/books/11 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refactoring",
    "author": "Martin Fowler",
    "isbn": "978-0134757599",
    "genre": "Software Engineering",
    "pages": 455,
    "status": "RESERVED"
  }'

Example response

{
  "id": 11,
  "title": "Refactoring",
  "author": "Martin Fowler",
  "isbn": "978-0134757599",
  "genre": "Software Engineering",
  "pages": 455,
  "status": "RESERVED",
  "createdAt": "2026-04-13T14:20:00"
}

⁠5. Update only book status

Endpoint

PATCH /api/books/{id}/status

Description
Updates only the status field of a book.

Example request body

{
  "status": "BORROWED"
}

Example request

curl -X PATCH http://localhost:8081/api/books/11/status \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BORROWED"
  }'

Example response

{
  "id": 11,
  "title": "Refactoring",
  "author": "Martin Fowler",
  "isbn": "978-0134757599",
  "genre": "Software Engineering",
  "pages": 455,
  "status": "BORROWED",
  "createdAt": "2026-04-13T14:20:00"
}

⁠6. Delete a book

Endpoint

DELETE /api/books/{id}

Description
Deletes a book by ID.

Example request

curl -X DELETE http://localhost:8081/api/books/11

Example response

{
  "message": "Book with id 11 deleted successfully"
}

⁠7. Search books

Endpoint

GET /api/books/search

Description
Searches books by optional query parameters:

  • genre
  • status

You can use one of them or both together.

⁠7.1 Search by genre

Example request

curl "http://localhost:8081/api/books/search?genre=Fantasy"

Example response

[
  {
    "id": 1,
    "title": "The Hobbit",
    "author": "J.R.R. Tolkien",
    "isbn": "978-0261103344",
    "genre": "Fantasy",
    "pages": 310,
    "status": "AVAILABLE",
    "createdAt": "2026-04-13T14:00:00"
  }
]
⁠7.2 Search by status

Example request

curl "http://localhost:8081/api/books/search?status=AVAILABLE"

Example response

[
  {
    "id": 1,
    "title": "The Hobbit",
    "author": "J.R.R. Tolkien",
    "isbn": "978-0261103344",
    "genre": "Fantasy",
    "pages": 310,
    "status": "AVAILABLE",
    "createdAt": "2026-04-13T14:00:00"
  }
]
⁠7.3 Search by genre and status

Example request

curl "http://localhost:8081/api/books/search?genre=Programming&status=BORROWED"

Example response

[
  {
    "id": 6,
    "title": "The Pragmatic Programmer",
    "author": "Andrew Hunt",
    "isbn": "978-0135957059",
    "genre": "Programming",
    "pages": 352,
    "status": "BORROWED",
    "createdAt": "2026-04-13T14:00:00"
  }
]

⁠8. Count books

Endpoint

GET /api/books/count

Description
Returns the total number of books currently in memory.

Example request

curl http://localhost:8081/api/books/count

Example response

{
  "count": 10
}

⁠9. Seed info

Endpoint

GET /api/books/seed-info

Description
Returns information about the preloaded sample dataset.

Example request

curl http://localhost:8081/api/books/seed-info

Example response

{
  "message": "Sample book data loaded in memory",
  "count": 10
}

⁠10. Ping endpoint

Endpoint

GET /api/books/ping

Description
Simple test endpoint to verify that the API is running.

Example request

curl http://localhost:8081/api/books/ping

Example response

{
  "message": "Book Manager API is running"
}

⁠11. Version endpoint

Endpoint

GET /api/books/version

Description
Returns application metadata useful for Kubernetes rollout checks.

Example request

curl http://localhost:8081/api/books/version

Example response

{
  "app": "book-manager-api",
  "version": "1.0.0",
  "profile": "k8s-lab"
}

⁠Actuator Endpoints

⁠12. Health endpoint

Endpoint

GET /actuator/health

Description
Used by Kubernetes for readiness and liveness probes.

Example request

curl http://localhost:8081/actuator/health

Example response

{
  "status": "UP"
}

⁠13. Info endpoint

Endpoint

GET /actuator/info

Description
Returns application metadata.

Example request

curl http://localhost:8081/actuator/info

Example response

{
  "app": {
    "name": "book-manager-api",
    "version": "1.0.0",
    "profile": "k8s-lab"
  }
}

⁠Validation rules

The API validates incoming request bodies.

⁠Book creation and update rules

  • title: required
  • author: required
  • isbn: required and must contain only digits and hyphens
  • genre: required
  • pages: required, min 10, max 5000
  • status: required

Example validation error

{
  "timestamp": "2026-04-13T14:30:00",
  "status": 400,
  "error": "Bad Request",
  "validationErrors": {
    "title": "Title is required",
    "isbn": "ISBN must contain only digits and hyphens"
  }
}

⁠Sample statuses

Allowed values for status:

  • AVAILABLE
  • BORROWED
  • RESERVED

⁠Sample data loaded at startup

The application automatically loads sample books when it starts.

Example records include:

  • The Hobbit - Fantasy - AVAILABLE
  • Dune - Science Fiction - BORROWED
  • 1984 - Dystopian - AVAILABLE
  • The Alchemist - Adventure - RESERVED
  • Clean Code - Programming - AVAILABLE
  • The Pragmatic Programmer - Programming - BORROWED
  • Sapiens - History - AVAILABLE
  • The Name of the Wind - Fantasy - RESERVED
  • Atomic Habits - Self Help - AVAILABLE
  • Sherlock Holmes - Mystery - BORROWED

Since everything is stored in memory, restarting the application restores the original dataset.

⁠Running locally

⁠Start the application

mvn spring-boot:run

or build and run the jar:

mvn clean package
java -jar target/book-manager-api.jar

⁠Docker

⁠Build image

docker build -t YOUR_DOCKERHUB_USERNAME/book-manager-api:1.0.0 .

⁠Run container locally

docker run -p 8081:8081 YOUR_DOCKERHUB_USERNAME/book-manager-api:1.0.0

⁠Test container

curl http://localhost:8081/api/books
curl http://localhost:8081/actuator/health

⁠Push image

docker push YOUR_DOCKERHUB_USERNAME/book-manager-api:1.0.0

Optional latest tag:

docker tag YOUR_DOCKERHUB_USERNAME/book-manager-api:1.0.0 YOUR_DOCKERHUB_USERNAME/book-manager-api:latest
docker push YOUR_DOCKERHUB_USERNAME/book-manager-api:latest

⁠Kubernetes

⁠Apply manifests

kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

⁠Check resources

kubectl get pods
kubectl get deployments
kubectl get svc

⁠Describe deployment

kubectl describe deployment book-manager-api

⁠View logs

kubectl logs -l app=book-manager-api

⁠Kubernetes probes

The deployment uses:

  • readinessProbe on /actuator/health
  • livenessProbe on /actuator/health

This makes the application suitable for basic Kubernetes health checking demonstrations.

⁠Useful lab activities

Students can use this project to practice:

  • pulling a Docker image
  • running a container
  • testing REST endpoints
  • pushing a new image version
  • updating deployment tags
  • scaling replicas
  • exposing the service
  • observing liveness/readiness probes
  • checking rollout results through /api/books/version

⁠Notes

  • No database is used
  • Data is reset on every restart
  • The project is intentionally simple for infrastructure-focused labs
  • It is ideal for Docker and Kubernetes exercises

⁠Authoring idea for classroom usage

A good exercise flow could be:

  1. pull the image
  2. run it with Docker
  3. test the endpoints
  4. push a new version with a different tag
  5. update the Kubernetes deployment
  6. verify the new version from /api/books/version

⁠Coffeeware License

⁠Coffeeware

You can use, modify, share, and distribute this project freely.
If this project helps you, and we ever meet in person, you can buy me a coffee.

Author: Giovanni Pace
YouTube: https://www.youtube.com/@archetydev⁠

⁠Disclaimer

This project is intended for educational purposes.

⁠License

MIT License

Copyright (c) 2026 Giovanni Pace

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

⁠☕ Coffeeware Philosophy

If this project helped you build something useful or learn something new, consider offering a coffee ☕

The best way to support my work is by subscribing to my YouTube channel: https://youtube.com/@archety⁠

Tag summary

Content type

Image

Digest

sha256:652d8e3c0…

Size

109.8 MB

Last updated

6 months ago

docker pull archety/books-api-in-memory