[FEAT] New error handling and pagination #14

Merged

TomPlanche merged 3 commits from feat/error-handling-and-pagination into main

2025-10-31 14:20:47 +01:00

TomPlanche commented

2025-10-31 14:18:02 +01:00

(Migrated from github.com)

Summary

This PR introduces three major improvements to the API:

Robust error handling following Rust 2024-2025 best practices
Cleaner API response format aligned with REST standards
Pagination support for collection endpoints

Changes

Error Handling

Added dependencies: anyhow (with backtrace) and thiserror 2.0
Created src/error.rs: API error types with proper HTTP status mapping
- ValidationFailed → 400 Bad Request
- NotFound → 404 Not Found
- Internal → 500 (wraps anyhow errors, logs details but hides from users)
- Database → 500 (wraps SeaORM errors)
Updated src/db.rs: Uses anyhow::Result with rich context chains
Removed all unwrap()/expect() in production code
Added .context() at each error point for debugging narratives

API Response Format

New success format:
```
{
  "data": { ... }
}
```
New error format:
```
{
  "error": { "message": "..." }
}
```
HTTP status codes now only in response headers (removed from body)
Created src/response.rs: Standardized response structures with optional metadata

Pagination

Created src/pagination.rs: Query parameter validation and utilities
Query parameters: ?page=1&limit=20 (defaults: page=1, limit=20, max=100)
Response with metadata:

  {
  "_metadata": {
    "page": 1,
    "limit": 20,
    "pageCount": 20,
    "totalPages": 5,
    "totalCount": 100,
    "_links": {
      "self": "/secure/stickers?page=1&limit=20",
      "next": "/secure/stickers?page=2&limit=20"
    }
  },
  "data": { ... }
}

Updated endpoints:
- GET /secure/source - Paginated sources list
- GET /secure/stickers - Paginated stickers list

Testing

All changes pass strict clippy linting with pedantic rules
No warnings or errors
Backward compatible (pagination defaults maintain current behavior)

Breaking Changes

⚠️ Response format has changed:

Removed status and success fields from response body
Clients should rely on HTTP status codes instead

Example Usage

Default pagination

GET /secure/stickers

Custom pagination

GET /secure/stickers?page=2&limit=50

{
  "_metadata": {
    "_links": {
      "self": "/secure/stickers?page=2&limit=50",
      "next": "/secure/stickers?page=3&limit=50",
      "prev": "/secure/stickers?page=1&limit=50"
    }
  }
}

## Summary This PR introduces three major improvements to the API: 1. Robust error handling following Rust 2024-2025 best practices 2. Cleaner API response format aligned with REST standards 3. Pagination support for collection endpoints ## Changes ### Error Handling - **Added dependencies**: `anyhow` (with backtrace) and `thiserror 2.0` - **Created `src/error.rs`**: API error types with proper HTTP status mapping - `ValidationFailed` → 400 Bad Request - `NotFound` → 404 Not Found - `Internal` → 500 (wraps anyhow errors, logs details but hides from users) - `Database` → 500 (wraps SeaORM errors) - **Updated `src/db.rs`**: Uses `anyhow::Result` with rich context chains - **Removed all `unwrap()`/`expect()`** in production code - **Added `.context()`** at each error point for debugging narratives ### API Response Format - **New success format**: ```jsonc { "data": { ... } } - New error format: ```jsonc { "error": { "message": "..." } } ``` - HTTP status codes now only in response headers (removed from body) - Created src/response.rs: Standardized response structures with optional metadata Pagination - Created src/pagination.rs: Query parameter validation and utilities - Query parameters: ?page=1&limit=20 (defaults: page=1, limit=20, max=100) - Response with metadata: ```jsonc { "_metadata": { "page": 1, "limit": 20, "pageCount": 20, "totalPages": 5, "totalCount": 100, "_links": { "self": "/secure/stickers?page=1&limit=20", "next": "/secure/stickers?page=2&limit=20" } }, "data": { ... } } ``` - Updated endpoints: - GET /secure/source - Paginated sources list - GET /secure/stickers - Paginated stickers list Testing - All changes pass strict clippy linting with pedantic rules - No warnings or errors - Backward compatible (pagination defaults maintain current behavior) Breaking Changes ⚠️ Response format has changed: - Removed status and success fields from response body - Clients should rely on HTTP status codes instead Example Usage # Default pagination GET /secure/stickers # Custom pagination GET /secure/stickers?page=2&limit=50 # Navigation via metadata links ```jsonc { "_metadata": { "_links": { "self": "/secure/stickers?page=2&limit=50", "next": "/secure/stickers?page=3&limit=50", "prev": "/secure/stickers?page=1&limit=50" } } } ```