Syed Zubyl N | Software Developer - API

What I Learned Building Flutter Applications Around Real APIs

Syed Zubyl N — Mon, 18 May 2026 00:00:00 +0000

The Problem</h3>
Building a UI in Flutter is relatively straightforward. The real complexity begins when you connect that beautiful UI to a real-world, unpredictable REST API. Handling token expiration, offline states, local caching, and malformed JSON payloads quickly turns a simple app into a debugging nightmare.

Context</h3>
While building a mobile LMS (Learning Management System) application in Flutter, I needed to fetch course catalogs, stream videos, and issue certificates. This required robust communication with a backend API while ensuring the app remained responsive even when the user’s internet connection was spotty.

What I Tried</h3>
I initially relied solely on the network. Every time a user opened a screen, a `FutureBuilder</code> would fire off an HTTP request and display a loading spinner until the data arrived.`

What Failed</h3> Poor UX: Users stared at loading spinners constantly.</li> Offline Experience: If a user boarded a subway, the app became completely useless. It crashed or showed generic error screens.</li> API Rate Limiting: Spamming the backend with requests every time a user switched tabs was highly inefficient.</li> </ol> What Worked & Technical Explanation</h3> I shifted to a Local-First Architecture using SQLite (via the sqflite</code> package). Instead of the UI talking directly to the API, the UI only talks to the local SQLite database. A separate background synchronization engine talks to the API. The Flow: User opens the Course List screen.</li> The UI reads immediately from SQLite and displays cached data (instant load).</li> In the background, the app fires an API request to check for updates.</li> If the API returns new data, it updates the SQLite database.</li> The UI, listening to a stream from the database, automatically rebuilds with the fresh data.</li> </ol> Handling API Failures: If an API request fails (e.g., user is offline, or the server returns a 500 error), the app simply logs the failure silently. The user is still looking at the cached data from SQLite and can continue interacting with the app. Lessons Learned</h3> Never trust the network. The network will fail, it will be slow, and it will return unexpected data.</li> Defensive Parsing: Always wrap JSON parsing in try-catch blocks or use robust code-generation tools. One unexpected null</code> field from the backend can crash the entire Flutter isolate.</li> Local State is King: For an app to feel fast and native, data must be available locally on the device the millisecond the screen renders.</li> </ol> What I Would Do Differently</h3> Instead of writing raw SQL queries for SQLite, I would adopt a higher-level reactive database like Isar or ObjectBox. They provide out-of-the-box stream capabilities that make tying local database updates directly to Flutter’s reactive UI significantly easier than building custom StreamControllers</code> over sqflite</code>.

Designing a Reliable API Layer for a Mobile Application Syed Zubyl N — Sun, 22 Mar 2026 00:00:00 +0000 The Problem</h3> In the early stages of a mobile LMS application, HTTP requests were scattered directly inside UI widgets. Buttons would execute http.get</code>, parse JSON inline, and call setState</code>. This quickly became unmaintainable. Token expiration caused random crashes, error handling was inconsistent, and mocking data for tests was impossible. Context</h3> A robust mobile application requires a strict separation of concerns. The UI should only care about displaying state, not fetching it. The networking layer must handle token injection, timeouts, retries, and error standardization before the data ever reaches the UI. What I Tried</h3> I initially tried to create a single massive ApiService</code> class that contained every single endpoint in the application. What Failed</h3> The ApiService</code> file grew to thousands of lines. When multiple developers worked on different features (Authentication, Courses, User Profile), merge conflicts became a daily nightmare. Furthermore, handling token refreshes on a per-method basis resulted in heavily duplicated code. What Worked & Technical Explanation</h3> I re-architected the API layer into a layered, modular system based on the Repository Pattern and Interceptors. 1. The Base HTTP Client (The Interceptor Layer) Instead of using raw http.Client</code>, I implemented a wrapper (using packages like dio</code> or custom http.BaseClient</code> implementations) that intercepts every request. Request Interceptor: Automatically injects the Authorization: Bearer <token></code> header from secure storage into every outgoing request.</li> Response Interceptor: Global error handling. If a 401 Unauthorized</code> is returned, the interceptor pauses all outgoing requests, silently hits the refresh-token endpoint, updates secure storage, and retries the failed requests.</li> </ul> 2. Domain-Specific Repositories Instead of one massive API class, I created focused repositories: AuthRepository</code>: Handles login, registration, and token management.</li> CourseRepository</code>: Fetches course lists and lesson details.</li> VideoRepository</code>: Manages video streaming URLs and playback telemetry.</li> </ul> 3. Standardized Result Wrappers Instead of throwing exceptions directly into the UI, repositories return a standardized Result type (often using Dart’s Either</code> pattern via the fpdart</code> or dartz</code> package). Future<Either<ApiFailure, Course>> getCourseDetails(String id) async { try { final response = await _client.get('/courses/$id'); return Right(Course.fromJson(response.data)); } on DioError catch (e) { return Left(ApiFailure.fromDioError(e)); } }</code></pre>Lessons Learned</h3> Separating the UI from the network layer is non-negotiable for production apps. The complexity of handling network latency, offline states, and token lifecycles must be encapsulated so the UI can remain declarative and clean. What I Would Do Differently</h3> I would implement local caching (using SQLite) much earlier in the architecture. While the API layer was robust, relying entirely on network availability resulted in a poor experience on slow connections. Integrating a repository that checks local storage before hitting the API is the next logical step. When API Response Types Don't Match Your Flutter Model Syed Zubyl N — Thu, 05 Mar 2026 00:00:00 +0000 The Problem</h3> A Flutter application was crashing on the profile screen with a cryptic error in the console: type 'int' is not a subtype of type 'bool?'</code></pre> The app compiled perfectly, the API returned a 200 OK, but the JSON deserialization failed entirely, resulting in a red screen of death in debug mode (and a blank screen in production). Context</h3> In Dart, type safety is strict. When you parse a JSON response, you typically map a Map<String, dynamic></code> into a strongly-typed Dart object. Our model looked like this: class UserProfile { final String name; final bool? isPremium; UserProfile({required this.name, this.isPremium}); factory UserProfile.fromJson(Map<String, dynamic> json) { return UserProfile( name: json['name'], isPremium: json['isPremium'], ); } }</code></pre>What I Tried</h3> I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>). What Failed</h3> Ignoring the type cast didn’t work. The exception specifically complained about an int</code>. What Worked & Technical Explanation</h3> I intercepted the raw HTTP response body before it hit the Dart parser. { "name": "Syed", "isPremium": 1 }</code></pre> The backend developer had migrated the database, and the new database driver was serializing SQL TINYINT(1)</code> boolean columns into 1</code> and 0</code> integers in the JSON payload, rather than true</code> and false</code>. Because json['isPremium']</code> contained an integer 1</code>, Dart crashed when it implicitly tried to cast it to bool?</code>. To fix this, I implemented defensive serialization. Instead of trusting the API contract blindly, the Dart parser needs to handle potential type coercion gracefully: factory UserProfile.fromJson(Map<String, dynamic> json) { // Defensive parsing function bool? parseBool(dynamic value) { if (value == null) return null; if (value is bool) return value; if (value is int) return value == 1; if (value is String) return value.toLowerCase() == 'true'; return null; } return UserProfile( name: json['name'] ?? 'Unknown', isPremium: parseBool(json['isPremium']), ); }</code></pre>Lessons Learned</h3> API Contracts Drift: Backend implementations change, and serialization layers can inadvertently alter the types of JSON payloads (especially converting booleans to integers or numbers to strings).</li> Dart is Unforgiving: Unlike JavaScript, Dart will not automatically coerce 1</code> into true</code>. You must handle the conversion explicitly.</li> </ol> What I Would Do Differently</h3> I will use code-generation tools like json_serializable</code> or freezed</code> with custom JsonConverter</code> classes for primitive types. This abstracts away the boilerplate of defensive parsing and ensures the entire app handles API type mismatches consistently. Debugging a 405 Method Not Allowed Error in a Mobile API Syed Zubyl N — Sat, 14 Feb 2026 00:00:00 +0000 The Problem</h3> While developing a mobile application, a specific API endpoint for fetching user profile data suddenly started failing. The mobile client was receiving a 405 Method Not Allowed</code> HTTP status code, and the data refused to load. Context</h3> The application relies on a Spring Boot backend exposing RESTful endpoints. The mobile client (built in Flutter) communicates with this API using the http</code> package. The endpoint in question was /api/v1/users/profile</code>. What I Tried</h3> At first, I assumed the authentication token was invalid or the endpoint URL was misspelled. I checked the JWT token — it was valid.</li> I verified the URL string in the Dart code — it perfectly matched the backend controller.</li> I checked the server logs, expecting to see a NullPointerException</code> or a 400 Bad Request</code>. Instead, Spring Security was just quietly rejecting the request at the filter level.</li> </ol> What Failed</h3> I spent an hour looking at the backend logic, assuming the database query was failing or the routing was broken. None of this was the issue because the request wasn’t even reaching my controller method. What Worked & Technical Explanation</h3> The breakthrough came when I bypassed the mobile app entirely and used Postman to test the endpoint. When I sent a GET</code> request in Postman: 200 OK. When I looked closely at my Flutter network layer: // The bug final response = await http.post( Uri.parse('https://api.example.com/api/v1/users/profile'), headers: {'Authorization': 'Bearer $token'}, );</code></pre> The issue was glaringly simple: I was using http.post</code> for an endpoint that the backend explicitly defined as a @GetMapping</code>. A 405 Method Not Allowed</code> means exactly what it says: the server exists, the route exists, but the HTTP verb (GET, POST, PUT, DELETE) you used is not supported for that specific route. It is fundamentally different from a 404 Not Found</code> (route doesn’t exist) or a 400 Bad Request</code> (payload is wrong). I corrected the mobile client to use http.get</code>: // The fix final response = await http.get( Uri.parse('https://api.example.com/api/v1/users/profile'), headers: {'Authorization': 'Bearer $token'}, );</code></pre>Lessons Learned</h3> Read the HTTP Status Code literally. Don’t assume a 405 is a generic crash. It has a highly specific meaning defined by the HTTP protocol.</li> Isolate the client from the server. When an API fails in a mobile app, test the exact same request in curl</code> or Postman immediately. This tells you instantly if the bug is in the client code (Flutter) or the server code (Spring Boot).</li> </ol> What I Would Do Differently</h3> I will implement a centralized API client class in Flutter with strict typed methods (fetchProfile()</code>, updateProfile()</code>) rather than writing raw http.get</code> or http.post</code> calls scattered throughout the UI code. This reduces the surface area for simple typo bugs like using the wrong HTTP verb.

Syed Zubyl N | Software Developer - API

What I Learned Building Flutter Applications Around Real APIs

What I Tried</h3>
I initially relied solely on the network. Every time a user opened a screen, a `FutureBuilder</code> would fire off an HTTP request and display a loading spinner until the data arrived.</p>`

Designing a Reliable API Layer for a Mobile Application

Lessons Learned</h3>
Separating the UI from the network layer is non-negotiable for production apps. The complexity of handling network latency, offline states, and token lifecycles must be encapsulated so the UI can remain declarative and clean.</p>

When API Response Types Don't Match Your Flutter Model

What I Tried</h3>
I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that `isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>).</p>`

Debugging a 405 Method Not Allowed Error in a Mobile API

The Problem</h3>
While developing a mobile application, a specific API endpoint for fetching user profile data suddenly started failing. The mobile client was receiving a `405 Method Not Allowed</code> HTTP status code, and the data refused to load.</p>`

What Failed</h3>
I spent an hour looking at the backend logic, assuming the database query was failing or the routing was broken. None of this was the issue because the request wasn’t even reaching my controller method.</p>

Syed Zubyl N | Software Developer - API

What I Learned Building Flutter Applications Around Real APIs

What I Tried</h3> I initially relied solely on the network. Every time a user opened a screen, a FutureBuilder</code> would fire off an HTTP request and display a loading spinner until the data arrived.</p>

Designing a Reliable API Layer for a Mobile Application

Lessons Learned</h3> Separating the UI from the network layer is non-negotiable for production apps. The complexity of handling network latency, offline states, and token lifecycles must be encapsulated so the UI can remain declarative and clean.</p>

When API Response Types Don't Match Your Flutter Model

What I Tried</h3> I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>).</p>

Debugging a 405 Method Not Allowed Error in a Mobile API

The Problem</h3> While developing a mobile application, a specific API endpoint for fetching user profile data suddenly started failing. The mobile client was receiving a 405 Method Not Allowed</code> HTTP status code, and the data refused to load.</p>

What Failed</h3> I spent an hour looking at the backend logic, assuming the database query was failing or the routing was broken. None of this was the issue because the request wasn’t even reaching my controller method.</p>

What I Tried</h3>
I initially relied solely on the network. Every time a user opened a screen, a `FutureBuilder</code> would fire off an HTTP request and display a loading spinner until the data arrived.</p>`

Lessons Learned</h3>
Separating the UI from the network layer is non-negotiable for production apps. The complexity of handling network latency, offline states, and token lifecycles must be encapsulated so the UI can remain declarative and clean.</p>

What I Tried</h3>
I checked the backend documentation (Swagger/OpenAPI). The documentation clearly stated that `isPremium</code> was a boolean. I assumed the issue was a null value since isPremium</code> might not exist for legacy users, but I had already marked it as nullable (bool?</code>).</p>`

The Problem</h3>
While developing a mobile application, a specific API endpoint for fetching user profile data suddenly started failing. The mobile client was receiving a `405 Method Not Allowed</code> HTTP status code, and the data refused to load.</p>`

What Failed</h3>
I spent an hour looking at the backend logic, assuming the database query was failing or the routing was broken. None of this was the issue because the request wasn’t even reaching my controller method.</p>