Module api 

REST API endpoints for the Hammerwork web dashboard.

This module provides a comprehensive REST API for job queue management, including endpoints for jobs, queues, statistics, and system information. All API responses use a standardized format with proper error handling.

API Response Format

All API endpoints return responses in a consistent format:

use hammerwork_web::api::ApiResponse;
use serde_json::json;

// Success response
let success_response = ApiResponse::success(json!({"count": 42}));
assert!(success_response.success);
assert!(success_response.data.is_some());
assert!(success_response.error.is_none());

// Error response
let error_response: ApiResponse<()> = ApiResponse::error("Something went wrong".to_string());
assert!(!error_response.success);
assert!(error_response.data.is_none());
assert!(error_response.error.is_some());

Pagination

Many endpoints support pagination using query parameters:

use hammerwork_web::api::{PaginationParams, PaginationMeta};

let params = PaginationParams {
    page: Some(2),
    limit: Some(50),
    offset: None,
};

assert_eq!(params.get_limit(), 50);
assert_eq!(params.get_offset(), 50); // (page-1) * limit

let meta = PaginationMeta::new(&params, 200); // 200 total items
assert_eq!(meta.page, 2);
assert_eq!(meta.total_pages, 4);
assert!(meta.has_next);
assert!(meta.has_prev);

Modules

archive

Archive management API endpoints.

history

Historical job queries backing the dashboard’s trend, error-pattern and clear endpoints.

jobs

Job management API endpoints.

queues

Queue management API endpoints.

stats

Statistics and monitoring API endpoints.

system

System information and administration API endpoints.

Structs

ApiResponse

Standard API response wrapper

FilterParams

Query filter parameters

PaginatedResponse

Paginated response wrapper

PaginationMeta

Pagination metadata for responses

PaginationParams

Pagination parameters

SortParams

Sort parameters

Constants

DEFAULT_PAGE_SIZE

The page size when a request does not give one.

MAX_PAGE_SIZE

The largest page size a request may ask for; larger limits are clamped to it.

Functions

error_reply

Build a JSON ApiResponse error body with the given HTTP status.

handle_api_error

Common error handling for API endpoints

internal_error

Log a failed backend operation and return it as a 500 Internal Server Error JSON response ("{context}: {err}").

json_reply

Serialize body as a 200 OK JSON response.

queue_error_reply

Turn a failed queue operation into a JSON error reply: a missing job is a 404, a transition the job’s status does not allow a 409, anything else a logged 500.

with_filters

Extract filter parameters from query string

with_pagination

Extract pagination parameters from query string

with_sort

Extract sort parameters from query string