Flutter Dart APIs and HTTP

Requests, responses, status codes, JSON payloads, authentication, and API boundaries.

Chapter goal: Requests, responses, status codes, JSON payloads, authentication, and API boundaries.

Simple explanation

An API is like a restaurant waiter. Your app sends a request, another system handles it, and a response comes back.

In Flutter Dart, this chapter is about communicating with services outside your app. Start with the idea above. Then connect each symbol to a value or action in the example.

Do not try to remember every symbol. First ask what data the program has, what it does with that data, and what result it creates. Technical words become easier when you connect them to those three questions.

Why this topic is important

Modern apps depend on APIs for login, payments, content, AI, analytics, and storage. In Flutter Dart, the syntax may look different from other languages, but the thinking skill transfers: name the data, choose the right operation, and make the next step obvious.

When to use it

Use APIs when your program needs data or actions from another system.

Example code

final response = await http.get(Uri.parse("https://example.com/api/lessons"));
if (response.statusCode == 200) {
  print(response.body);
}

Line-by-line explanation

• final response = await http.get(Uri.parse("https://example.com/api/lessons")); — This waits for asynchronous work to finish without pretending the result is already available.
• if (response.statusCode == 200) { — This checks a true-or-false condition. The controlled block runs only when that condition is true.
• print(response.body); — This is the visible output line. It shows the final value after the earlier work is complete.

What the output means

The response data is displayed only when the request succeeds.

The output is evidence that the program followed the instructions. If your result is different, read from the first line and write down how each value changes. That is debugging, not failure.

Mistake example

final response = null; // the response status and response data are trusted blindly
if (response.statusCode == 200) {
  print(response.body);
}

This version intentionally shows how the response status and response data are trusted blindly. The changed assignment stores a missing value, or a required line is removed, so later code cannot complete its job safely.

Fixed version

final response = await http.get(Uri.parse("https://example.com/api/lessons"));
if (response.statusCode == 200) {
  print(response.body);
}

The corrected version restores the real value or required operation. It fixes the chapter-specific problem: the response status and response data are trusted blindly.

Common mistakes

• Ignoring status codes.
• Trusting response data without checks.
• Hardcoding tokens in client code.

Warning: Change one part at a time. If you change many lines together, it becomes harder to learn which change caused the result.

Real use cases

• Fetch lessons.
• Submit contact forms.
• Sync user progress to a backend.

Small real-project example

A lessons screen fetches data and returns a different widget for success, failure, and connection loss.

Future<Widget> loadLessonsScreen() async {
  try {
    final response = await http.get(Uri.parse('https://example.com/api/lessons'));
    if (response.statusCode == 200) {
      return LessonList(body: response.body);
    }
    return const ErrorMessage('Lessons could not be loaded');
  } catch (_) {
    return const ErrorMessage('No internet connection');
  }
}

How the project example works

• The request runs inside try, so a lost connection cannot crash the screen.
• response.statusCode == 200 confirms the server accepted the request before using the body.
• A non-200 status returns a friendly ErrorMessage, not raw response text.
• The catch covers no-connection failures separately from a bad server response.

Practice exercise

1. Handle a successful response.
2. Add a 404 or missing-data path.
3. Show loading, empty, and error states.

Tip: If the exercise feels too large, complete only steps 1 to 3. Small working code teaches more than a large unfinished project.

Mini quiz

1. What does a status code describe?
2. Why must response data be checked?
3. Where should a private API secret live?

How to read AI-generated code

Do not copy AI code first. Read it like a detective. Find the data, follow the changes, and locate the final output. Ask AI to explain a line only after you have made your own guess.

• What data goes in?
• What values are stored?
• What calculation or decision happens?
• What is printed, displayed, saved, or returned?
• What can go wrong?
• Can you rename one value and still explain the code?

Flutter reading check

Find the widget tree first. Then find which values can change, where setState is called, which callback handles the button or TextField, and where navigation or async data enters the screen.

Before you move on

• I can explain this topic in my own words.
• I can read the small example without AI.
• I can change the example and predict the new result.
• I can find and fix one simple mistake.
• I can name one real project that uses this idea.

Next topic

Next, learn async programming. Before opening it, explain this chapter out loud in under one minute.