API First
Problem
APIs often become an implementation detail of the backend instead of a deliberate contract between systems. That creates friction: frontend and backend teams duplicate models by hand, documentation drifts from reality, validation rules are discovered late, and integration problems only appear once both sides are wired together.
Constraints
The solution needs to support independent frontend and backend development, keep request and response models consistent, make validation and error responses explicit, and provide fast feedback when the API changes. It should also avoid adding unnecessary runtime complexity. In the task board example, the domain is small, but the same constraints are visible: projects, tasks, validation failures, and missing-project responses all need to mean the same thing in Spring Boot, Angular, tests, and documentation.
Architectural Choices
The API contract is defined first with OpenAPI. That contract becomes the source of truth for endpoints, request bodies, response models, and error shapes.
From that contract, the backend generates Spring interfaces and DTOs. The handwritten controllers then implement those generated interfaces, keeping business logic behind a contract-defined boundary. In the example, ProjectController and TaskController implement generated APIs instead of defining their own independent controller shape.
The frontend also generates its API client and TypeScript models from the same OpenAPI file. Thin Angular services wrap the generated client, so application code can stay clean while still benefiting from contract-generated types.
Tests focus on the API boundary. The HTTP tests verify successful flows, validation failures, and not-found responses, proving that the implemented service honors the public contract.
Alternatives
One alternative is backend-first development, where the backend implementation defines the API and the frontend adapts to it afterwards. This can work for small teams, but it often causes late integration issues and makes the API shape depend too much on backend internals.
Another option is frontend-first development with mocked endpoints. This helps UI progress, but without a formal contract, mocks can drift from the real backend.
A third option is manually maintained shared documentation and manually written clients. That avoids code generation, but it depends heavily on discipline. Over time, documentation, frontend types, backend DTOs, and tests can diverge.
Why This Solution
API-first makes the contract explicit before implementation details take over. It gives both frontend and backend a stable agreement to build against, while generated code reduces manual duplication.
It also makes change safer. When the OpenAPI contract changes, generated backend and frontend code change with it, so mismatches are caught earlier at build or test time instead of later during manual integration.
The result is a cleaner boundary between systems: the backend can evolve its internal implementation, the frontend can focus on user interaction and state, and both sides remain aligned through the same contract. This improves collaboration, reduces accidental API drift, and creates a stronger foundation for scaling the architecture beyond a small example.
View an API-First example project on GitHub.