The midnight endpoint
It started as a single endpoint for pulling the user profile, typically /me. In practice, when OAuth redirects fail, websocket connections misbehave, or localhost is blocked on some devices, debugging becomes a mix of network, authentication, and UI state inside the UI code itself.
Now imagine a better pattern where you fix the issue once in one place and the screens stop catching fire. This is not a dream. It is a design goal for resilient frontend architecture.
The pattern: boundary leak
This is not a Flutter problem. It is a boundary leak. When widgets, Cubits, or BLoCs know about base URLs and headers, token refresh rules, websocket reconnect logic, DTO parsing, backend error formats, and retry policies, you have not integrated an API. You have imported backend volatility into the UI layer.
As soon as the backend changes, the question changes from update to one adapter to ship to Why did this screen break
The pain is measurable (you are not imagining it)
Even in mature teams API integration can be blocked by context hunting. Consider these realities observed in practice:
- Many teams rely on internal docs while inconsistent docs remain the biggest roadblock.
- Developers frequently dig through source code to understand APIs and rely on colleagues to fill knowledge gaps.
Layer in AI assistance and you gain new verification challenges. A recent survey shows most developers spend time reviewing, testing, and correcting AI output, and a notable share say AI generated code requires more effort to review than code written by humans. When boundaries are fuzzy, AI does not solve the problem, it creates verification debt.
How we build (values)
We do not ship vibes alone. We ship clear boundaries that keep the app calm even when the backend is unstable. Boundaries enable predictable behavior and reduce the risk of backend volatility leaking into the UI.
The standard
Include this in your repository as API_INTEGRATION_STANDARD.md and enforce it in pull requests. A shared standard creates a common language for teams and speeds up onboarding.
API Integration Standard (Flutter + Clean Architecture)
The standard aligns with a clean architectural approach where responsibilities are separated into layers with strict contracts between them. UI code must never own networking, token management, or parsing logic. Instead, it should delegate to application services and rely on domain contracts that are implemented by data sources.
Non-negotiables
1) No http or dio, websocket clients, token refresh, or parsing inside widgets, Cubits, or any UI state. 2) UI calls only UseCases (application layer). 3) UseCases call only Repository interfaces (domain contracts). 4) Repository implementations call DataSources (REST/WS/cache) and mappers. 5) No exceptions cross layers. Normalize everything to AppFailure.
Practical steps to implement
Follow a disciplined path to enforce boundaries and reduce backend leakage into the frontend:
- Model your domain with clear Entities and UseCases that express business goals without UI concerns.
- Define Repository interfaces in the domain layer to abstract data access and error handling.
- Implement DataSources for REST, WebSocket, and cache layers with dedicated mappers to translate between raw backend data and domain models.
- Provide a centralized API client that manages base URLs, headers, token state, and global error translation into AppFailure.
- Adopt dependency injection to supply the correct adapters per environment and to facilitate testing.
- Normalize errors in a single place so UI components only react to AppFailure and not raw backend formats.
- Write tests for UseCases and Repositories to verify boundary integrity and to prevent regressions when the backend changes.
Required layer
Establish and document a layered architecture that enforces the boundary contracts. The UI should rely on the application layer for flows, which in turn relies on repository interfaces. DataSources implement the actual data access and map responses to domain models. This separation isolates backend changes to adapters, not the user interface, and makes the system far more maintainable over time.
Leave a Reply