An API response describes transport data. A Flutter screen also needs to represent loading, selected items, unsaved edits, stale content, and actions in progress. Using one object for both responsibilities makes server changes leak into interface behaviour.
Separate the boundary when the meanings differ. Keep the mapping explicit so missing fields, units, and lifecycle states cannot silently change what the user sees or submits.
Define three meanings before creating classes
The transport representation follows the API contract. The application's business representation captures concepts such as a request's status or owner. Presentation state describes the current interaction, including draft values and pending actions.
Flutter's architecture reference provides useful responsibility boundaries. You do not need three nearly identical classes for every trivial value; add separation where it preserves meaning or isolates change.
Map a fictional customer-request response
Suppose an endpoint returns an optional assignee identifier, a server status code, and an update timestamp. The screen needs a human-readable status, an unassigned state, a selected filter, and an unsent note.
Define how an unknown status is displayed and whether editing remains allowed. Decide whether an absent assignee means unassigned, unavailable information, or malformed data under the actual contract. Keep the selected filter and note draft out of the object sent back as a customer-record update.
Test a missing optional field, an unknown required value, an older response arriving after a newer one, and a server refresh while the user edits the note. The draft should not disappear simply because a transport object was replaced.
Make mapping failures visible at the right layer
Do not scatter fallback guesses across widgets. A single mapping boundary can produce a defined failure or partial-data state with safe diagnostic context. Preserve the original operation reference without exposing private payloads in ordinary logs.
Review write payloads separately. Sending a complete display object back to the server can overwrite fields the user never intended to change. State the actual action and validate it against current server rules.
The tradeoff is duplication versus independence. Mapping adds code and review work, but it can keep an API rename from forcing changes throughout the interface. For a small stable response used in one place, a simpler representation may be adequate. Reassess when transport details begin controlling interaction state.
The Social App portfolio account describes mobile and backend contributions. This request payload is fictional and does not claim its internal model design.
Questions about Flutter API models
Should every API object become a separate domain object?
Not automatically. Separate representations when they have different rules, lifecycles, or consumers. Avoid empty layers that only rename identical fields.
Where should loading state live?
With the feature's interaction state, alongside the current data and action status. It is not a property of the server's customer record.
What should a review test first?
Refresh data while a user has an unsaved edit, then deliver responses out of order. Bring unexpected state loss to a Flutter architecture review.