Book Catalog API

Project roadmap

1. 01

   Set up the project

   ~1.5h

   Create a Maven or Gradle project for Java 17 or newer with javalin, jackson-databind, jackson-datatype-jsr310 (for dates), postgresql, HikariCP and flyway-core. Read the database URL, user and password from environment variables. Start Javalin on port 7070 with GET /health returning {"status":"ok"}. Run PostgreSQL locally, for example with Docker. Done when: /health returns ok.

2. 02

   Create the schema with Flyway

   ~1.5h

   Write a Flyway migration V1__books.sql creating a books table: id (bigserial), isbn (unique), title, author, published_year, pages and created_at, with check constraints for a sensible year and a positive page count. Add V2__seed.sql with about 30 sample books. Run the migrations on startup. Done when: starting the app on an empty database creates and fills the table.

3. 03

   Write the data access layer

   ~2h

   Create a Book record and a BookRepository that uses a HikariCP DataSource and plain JDBC with PreparedStatement for findById, findPage (limit and offset), search, insert, update and delete. Turn a duplicate ISBN error (SQL state 23505) into a DuplicateIsbnException. Never build SQL by concatenating user input. Done when: every repository method works against the local database.

4. 04

   Add the CRUD endpoints

   ~2h

   Implement GET /books/{id}, POST /books, PUT /books/{id} and DELETE /books/{id}. Parse request bodies with Jackson and validate them: title and author required, an ISBN of 10 or 13 digits, a plausible year, positive pages. Return 201 with a Location header on create, 204 on delete, 404 for unknown ids and 409 for a duplicate ISBN. Done when: each endpoint works with curl and returns these codes.

5. 05

   Add search and pagination

   ~2h

   Implement GET /books?q=&author=&page=&size= with a case-insensitive title search (ILIKE with a parameter), an author filter, a default page size of 20 and a maximum of 100, and a stable order (title, then id). Return the items together with page, size and totalItems. Done when: searching and paging return correct, stable results, and invalid page values give 400.

6. 06

   Handle errors consistently

   ~1h

   Register exception handlers in Javalin so every error returns JSON like {"error":"...","details":[...]}: validation errors listing every invalid field (400), not found (404), duplicates (409), and unexpected errors (500) that are logged but never expose SQL or stack traces. Done when: every error response has the same JSON structure.

7. 07

   Write integration tests

   ~2.5h

   Write JUnit 5 tests that start PostgreSQL with Testcontainers, run the migrations and start the app on a random port. Use Java's HttpClient to test creating, reading, updating and deleting a book, a duplicate ISBN, invalid input, search and paging. Done when: the tests pass with Docker running and no manual database setup.

Resources

• DocsJavalin documentation
• DocsJackson databind
• DocsFlyway documentation
• DocsHikariCP
• DocsTestcontainers for Java