TimeTracker/docs/api/API_CONSISTENCY_AUDIT.md

API Consistency Audit

This document records the API consistency audit performed for the TimeTracker backend, REST API, and native clients (desktop and mobile). It describes findings and the standardized contracts adopted.

1. Response shapes

1.1 Success responses

• Helpers in app/utils/api_responses.py define success_response() (returns { "success": true, "data"?, "message"?, "meta"? }) and paginated_response() (items in data, pagination in meta.pagination).
• Actual API uses a different convention: list endpoints return resource-named key + top-level pagination, e.g. { "time_entries": [...], "pagination": {...} }, { "projects": [...], "pagination": {...} }. Single-resource responses use a singular key: { "time_entry": {...} }, { "project": {...} }, { "timer": {...} }.
• Contract (kept for compatibility): List = { "<resource_plural>": [...], "pagination": { page, per_page, total, pages, has_next, has_prev, next_page, prev_page } }. Single = { "<resource_singular>": {...} }. Created (201) = { "message"?, "<resource_singular>": {...} } or similar. Clients depend on these keys; we do not switch to data/meta.

1.2 Error responses (standardized)

• Contract: All API v1 error responses (4xx/5xx) include:
  • error (string): user-facing message (backward compatible).
  • message (string): same or more detail.
  • error_code (string, optional): machine-readable code, e.g. unauthorized, forbidden, not_found, validation_error, no_active_timer.
  • errors (object, optional): field-level validation errors, e.g. { "field_name": ["message1", "message2"] }.
  • For 403 scope errors: required_scope, available_scopes may also be present.

1.3 Validation errors

• Contract: Any 400 due to invalid input uses the same structure: error_code: "validation_error" and, when applicable, an errors object with field-level messages. Marshmallow validation uses handle_validation_error(); manual validation uses validation_error_response().

2. Pagination

• Contract: List endpoints support query params page (default 1) and per_page (default 50, max 100). Response includes "pagination": { "page", "per_page", "total", "pages", "has_next", "has_prev", "next_page", "prev_page" }. The list key is resource-specific (e.g. time_entries, projects), not items.

3. Auth / token handling

• Token extraction (Bearer, Token, X-API-Key) and @require_api_token(scope) are consistent. Auth error responses include error_code (unauthorized, forbidden) for consistent machine-readable handling.

4. Date/time

• Contract: Dates and datetimes use ISO 8601. Request parsing accepts YYYY-MM-DD and YYYY-MM-DDTHH:MM:SS / YYYY-MM-DDTHH:MM:SSZ. Serialization format (e.g. UTC or server local) is documented in the REST API reference.

5. Sort / filter

• Filter query parameters are resource-specific and documented per endpoint. Optional sort / order conventions may be documented for list endpoints that support them.

6. References

• REST API reference: REST_API.md — endpoints, request/response formats, pagination, errors.
• OpenAPI: /api/openapi.json and Swagger UI at /api/docs — aligned with this contract where updated. info.version follows get_version_from_setup() (from setup.py, with optional TIMETRACKER_VERSION / APP_VERSION overrides); see app/routes/api_docs.py.