Ktor REST API for a Bookshelf Manager

Project roadmap

1. 01

   Set up the Ktor project

   ~1.5h

   Generate a project at start.ktor.io (or with the IntelliJ plugin) with the Routing, Content Negotiation, kotlinx.serialization and Status Pages plugins. Add a GET /health route. Done when: the server starts and /health returns OK.

2. 02

   Define the database

   ~1.5h

   Add Exposed and the SQLite JDBC driver. Define a Books table with the Exposed DSL: id, title, author, genre, pages, status (an enum), rating (1 to 5, optional), added at and finished at. Connect at startup and create the table with SchemaUtils. Put the queries in a BookRepository class. Done when: books can be inserted and read through the repository.

3. 03

   Add the CRUD endpoints

   ~2h

   Add GET /books, GET /books/{id}, POST /books, PUT /books/{id} and DELETE /books/{id}, using @Serializable request and response classes separate from the table. Return 201 with the new book on create, 404 for unknown ids, and 204 on delete. Set finished at automatically when the status changes to finished. Done when: every endpoint works with curl and returns the right status codes.

4. 04

   Validate and handle errors

   ~1.5h

   Validate requests: the title and author are required (up to 200 characters), pages are between 1 and 10,000, and the rating is between 1 and 5 and only allowed for finished books. Use Status Pages to turn validation errors into 400 with a list of problems, malformed JSON into 400, and unexpected errors into 500 without internal details. Done when: invalid input gets clear 400 responses.

5. 05

   Add search and filters

   ~1.5h

   Support GET /books?q=&status=&genre=&sort=title|author|added&page=&size=. q searches title and author, ignoring case. Build the query conditionally with Exposed, and return the items with the total count. Add GET /books/stats with counts by status and pages read this year. Done when: search, filters and sorting combine correctly.

6. 06

   Write integration tests

   ~2h

   Write tests with testApplication and a fresh in-memory or temporary SQLite database per test: creating and fetching books, updates setting finished at, validation errors, 404s, search and filters, and stats. Done when: ./gradlew test passes.

Resources

• DocsKtor: creating a REST API
• DocsKtor: Status Pages
• DocsKtor: testing
• DocsExposed documentation
• Docskotlinx.serialization guide