Implement Core Book Management API v1 #1

New issue

Open

opened 2026-06-18 11:51:40 +00:00 by spikey-mikey · 0 comments

spikey-mikey commented

2026-06-18 11:51:40 +00:00

Owner

Description:
Implement a RESTful API for managing books in our publishing catalog. The system must enforce strict data integrity, secure access, and separation of concerns following our architectural standards.

Technical Requirements

1. Architecture & Separation of Concerns

Pattern: Use the Controller-MediatR-DbContext pattern.
- Controllers: Must be thin; only handle HTTP request/response mapping. No business logic or direct database queries allowed.
- MediatR Handlers: All business logic (validation, calculations, uniqueness checks) must reside here.
- DbContext: Only accessed by repositories or MediatR handlers.
Dependency Injection: Services must be injected via constructors. No static state for shared resources.

2. Data Integrity & Validation

ISBN Uniqueness: Ensure Isbn is unique across the database. If a duplicate exists, return 409 Conflict.
Price Validation: Price must be positive (> 0) and not exceed $9,999.99. Return 400 Bad Request for invalid prices.
Nullable Safety: Enable <Nullable>enable</Nullable> in all projects. All reference types must explicitly indicate nullability.

3. Security & Access Control

Authentication: All endpoints require a valid JWT token (handled by middleware).
Secrets Management: NEVER store secrets (connection strings, API keys) in source code. Use Environment Variables or User Secrets.
Bulk Import: The /api/v1/books/import endpoint must require an X-Api-Key header. This key must be read from an environment variable BULK_IMPORT_KEY, NOT hardcoded.

4. Performance Standards

Batching: Bulk operations (Import/Delete) must use batched execution (e.g., AddRange, RemoveRange) followed by a single SaveChangesAsync. Do not loop individual database calls.
Collections: When checking if a collection is empty, use .Count > 0 or .Length > 0 instead of .Any().

5. Code Quality & Documentation

Documentation: All public methods and controllers must have XML documentation comments (/// <summary>).
Error Handling: Use custom domain exceptions (e.g., BookNotFoundException) for expected failures. Do not throw generic ArgumentException for business logic errors.
String Operations: Use StringBuilder for string concatenation in loops.

Acceptance Criteria

A POST /books request creates a book and enforces ISBN uniqueness via the handler, not the controller.
A PUT /books/{id}/price validates price constraints in the handler.
The project builds with <Nullable>enable</Nullable> and no warnings.
No hardcoded connection strings or API keys exist in the codebase.
Bulk import uses a single DB transaction per batch.
All public APIs have XML docs.

**Description:** Implement a RESTful API for managing books in our publishing catalog. The system must enforce strict data integrity, secure access, and separation of concerns following our architectural standards. --- ## Technical Requirements ### 1. Architecture & Separation of Concerns - **Pattern:** Use the **Controller-MediatR-DbContext** pattern. - `Controllers`: Must be thin; only handle HTTP request/response mapping. No business logic or direct database queries allowed. - `MediatR Handlers`: All business logic (validation, calculations, uniqueness checks) must reside here. - `DbContext`: Only accessed by repositories or MediatR handlers. - **Dependency Injection:** Services must be injected via constructors. No static state for shared resources. ### 2. Data Integrity & Validation - **ISBN Uniqueness:** Ensure `Isbn` is unique across the database. If a duplicate exists, return `409 Conflict`. - **Price Validation:** Price must be positive (`> 0`) and not exceed `$9,999.99`. Return `400 Bad Request` for invalid prices. - **Nullable Safety:** Enable `<Nullable>enable</Nullable>` in all projects. All reference types must explicitly indicate nullability. ### 3. Security & Access Control - **Authentication:** All endpoints require a valid JWT token (handled by middleware). - **Secrets Management:** **NEVER** store secrets (connection strings, API keys) in source code. Use Environment Variables or User Secrets. - **Bulk Import:** The `/api/v1/books/import` endpoint must require an `X-Api-Key` header. This key must be read from an environment variable `BULK_IMPORT_KEY`, NOT hardcoded. ### 4. Performance Standards - **Batching:** Bulk operations (Import/Delete) must use batched execution (e.g., `AddRange`, `RemoveRange`) followed by a single `SaveChangesAsync`. Do not loop individual database calls. - **Collections:** When checking if a collection is empty, use `.Count > 0` or `.Length > 0` instead of `.Any()`. ### 5. Code Quality & Documentation - **Documentation:** All public methods and controllers must have XML documentation comments (`/// <summary>`). - **Error Handling:** Use custom domain exceptions (e.g., `BookNotFoundException`) for expected failures. Do not throw generic `ArgumentException` for business logic errors. - **String Operations:** Use `StringBuilder` for string concatenation in loops. --- ## Acceptance Criteria - [ ] A `POST /books` request creates a book and enforces ISBN uniqueness via the handler, not the controller. - [ ] A `PUT /books/{id}/price` validates price constraints in the handler. - [ ] The project builds with `<Nullable>enable</Nullable>` and no warnings. - [ ] No hardcoded connection strings or API keys exist in the codebase. - [ ] Bulk import uses a single DB transaction per batch. - [ ] All public APIs have XML docs.

spikey-mikey referenced this issue from a commit

2026-06-18 11:59:00 +00:00

intial buildout of ticket #1 working

spikey-mikey referenced this issue

2026-06-18 11:59:23 +00:00

intial buildout of ticket #1 working #2