backend-api-design

Backend API Design — Quick Reference

URL Patterns

GET  /api/v1/employees              # List (plural)
GET  /api/v1/employee               # Get one (?id=xxx)
POST /api/v1/employee               # Create
POST /api/v1/employee/update        # Update (?id=xxx)
POST /api/v1/employee/delete        # Soft delete (?id=xxx)
POST /api/v1/employee/restore       # Restore (?id=xxx)
POST /api/v1/sync/employees         # Action

Hard Rules

• NO path params — always @QueryValue, never @PathVariable
• Singular for single resource — /employee not /employees/{id}
• Plural for collections — /employees
• Verb sub-paths for actions — /delete, /restore, /sync

Layered Architecture

Controller  →  thin, just delegates
    ↓
Manager     →  business logic, transactions, Either returns
    ↓
Repository  →  data access only, no business logic

Controller: Thin Wrapper

• Parse query params with defaults
• Delegate to manager
• Unwrap Either with .throwOrValue()
• NO business logic, NO repository access

Manager: Business Logic

• Returns Either<ClientException, T>
• Wraps DB ops in transaction(db.primary) { }
• Orchestrates multiple repositories
• Validates business rules

Repository: Data Access

• Returns entities or null
• db.replica for reads, db.primary for writes
• Always checks deletedAt.isNull()

Quick Code Reference

The core controller delegation pattern:

@Get("/employee")
suspend fun getEmployee(@QueryValue id: UUID): EmployeeResponse {
  return employeeManager.findById(id).throwOrValue()
}

• Response models — companion object { fun from(entity) } in module-client/response/{domain}/
• Pagination — offset-based, manager returns EmployeeListResponse with items, total, page, limit, hasMore
• Errors — return ClientError.NOT_FOUND.asException().left() from managers, never throw
• Factory beans — @Factory class with @Singleton method, wire repos + db into manager