ADR-003: API Style

Status: Accepted Date: 2026-02-07

Context

The frontend needs to fetch deeply nested data (project > timeline > section > item) and graph-shaped data (characters + relationships for visualization). The team needed to choose between REST, GraphQL, or a hybrid approach.

Decision

REST + custom endpoints. Standard REST for CRUD operations, with purpose-built endpoints for complex read views like relationship graphs.

Rationale

• REST is familiar to the team and straightforward to implement in .NET
• Standard CRUD endpoints cover the majority of operations
• Custom graph endpoints (/api/projects/{key}/graphs/characters) return pre-assembled data for visualization in a single call
• Lower upfront complexity than GraphQL
• Permission middleware is simpler to implement on REST endpoints
• GraphQL can be reconsidered later if the team has expertise (see team discussion items)

Alternatives Considered

• Pure REST - Would require multiple calls to assemble relationship maps. Custom endpoints avoid this
• GraphQL - Natural fit for nested/graph data. Frontend asks for exactly what it needs. Rejected due to learning curve, additional library (Hot Chocolate), and more complex auth middleware. May reconsider if team has experience
• gRPC - Overkill for a web application frontend. Better suited for service-to-service communication

URL Conventions

• All endpoints nested under project: /api/projects/{key}/...
• {key} = project key (e.g., VNO)
• {seq} = public sequence number (e.g., 42)
• Child entities (sections, items) use flat URLs under the project rather than deep nesting

Consequences

• Controllers organized by feature (ProjectsController, TimelinesController, CharactersController)
• Graph endpoints need dedicated query logic to assemble nodes + edges with permission filtering
• API versioning strategy decided in ADR-010: URL path prefix with pragmatic policy