Fitness Tracking API
Production-grade REST API with RBAC, HATEOAS, and ETag caching
Problem
Modern fitness applications demand APIs that go beyond basic CRUD. The challenge: design a system handling complex user hierarchies (admins, coaches, athletes), enforce fine-grained access control across all resources, and remain self-documenting at runtime — all while maintaining high test coverage and performance under realistic load.
Approach
Designed around REST Level 3 (HATEOAS) so clients navigate via hypermedia links rather than hardcoded URLs. JWT tokens with short expiry and rotating refresh tokens handle authentication. RBAC was modeled as a permission matrix rather than simple role checks, enabling granular control across endpoints without a growing pile of conditionals.
Architecture
Layered architecture with strict separation between HTTP handling, business logic, and data access. No layer knows the implementation details of the layer below.
HTTP Layer
Koa middleware pipeline — CORS, rate limiting, auth validation, request parsing
Router Layer
Thin route handlers that delegate immediately to the service layer — no logic here
Service Layer
Business logic, authorization checks, cross-entity operations, HATEOAS link generation
Repository Layer
All DB queries in typed repository classes — no raw SQL ever reaches the service layer
Database
MySQL with connection pooling, parameterized queries, and transaction support
Key Engineering Decisions
Refresh token rotation over long-lived JWTs
Short-lived access tokens (15 min) with rotating refresh tokens limit the blast radius of a leaked token. If a refresh token is reused, the system detects token family compromise and invalidates the entire session immediately.
RBAC as a permission matrix, not role conditionals
Rather than checking role names at each endpoint, permissions are resolved to a resource×action matrix on login. Middleware checks are O(1) hash lookups — the permission model scales to hundreds of roles without touching endpoint code.
ETag-based conditional caching
ETags generated from content hashes let clients skip re-parsing unchanged responses. Cache validation reduces downstream bandwidth by ~60% in typical read-heavy workloads without any risk of serving stale data.
HATEOAS for API discoverability
Every response includes hypermedia links to valid next actions for the current user's role. Clients never construct URLs — they follow links. This decouples URL structure from clients and makes the API self-documenting at runtime.
Security Considerations
Parameterized queries block SQL injection throughout. JWT signatures use RS256 (asymmetric keys) so the public key can verify tokens without exposing the signing secret to any service. Input validation runs at the router layer using strict schemas, rejecting malformed requests before they reach business logic. Rate limiting on auth endpoints prevents brute force and credential stuffing.
Testing Strategy
Integration tests hit a real MySQL test database — no mocks at the data layer to hide divergence. Each test resets state via transactions that roll back after the assertion. Unit tests cover the service layer in isolation with stubbed repositories. CI blocks merges below line and branch coverage threshold.
Outcome
Production-ready API with full Level 3 REST compliance, zero known OWASP Top 10 vulnerabilities, a comprehensive test suite, and OpenAPI 3.0 documentation with live Swagger UI. The architecture handles new role types and permission rules without touching existing endpoint logic.
Interested in working together?
Let's discuss your next project.