Skip to main content

Fetch data from the internet

Refactor your application to use a robust, production-ready API client for the Wikipedia CLI.

In Chapter 3, you used the http package to make a simple request. Now, you'll revisit HTTP to build a robust, production-ready API client within the wikipedia package. You'll learn how to handle query parameters, map JSON responses to your data models, and export these functions for use in your CLI.

What you'll accomplish

Construct complex URIs with query parameters
Create a production-ready HTTP API client
Export functions and types for reuse

Prerequisites

#

Before you begin this chapter, ensure you:

  • Have completed Chapter 11 and have a working Dart development environment with the dartpedia project.
  • Understand basic networking concepts (like APIs and HTTP requests).
  • Understand basic data serialization formats such as JSON.

Tasks

#

In this chapter, you'll move beyond simple scripts and implement a proper API layer. You'll work within the wikipedia package to implement the API client logic, which improves your application's scalability and maintainability.

Task 1: Add the http dependency to the wikipedia package

#

To make HTTP requests, you need to add the http package as a dependency to the wikipedia package.

  1. Open the wikipedia/pubspec.yaml file within your project.

  2. Locate the dependencies section.

  3. Add http: ^1.3.0 (or the latest stable version) under dependencies.

    wikipedia/pubspec.yaml
    yaml
    dependencies:
      http: ^1.3.0
    
  4. Save the pubspec.yaml file.

  5. Run dart pub get in your terminal from the wikipedia directory.

Task 2: Implement Wikipedia API calls

#

Next, you'll create the API functions to fetch data from Wikipedia. You'll create three files:

  • summary.dart: This file will contain functions for retrieving article summaries.
  • search.dart: This file will handle search queries to find articles.
  • get_article.dart: This file will contain functions for fetching the full content of an article.
  1. Create the directory wikipedia/lib/src/api.

  2. Create the file wikipedia/lib/src/api/summary.dart.

  3. Add the following code to wikipedia/lib/src/api/summary.dart:

    wikipedia/lib/src/api/summary.dart
    dart
    import 'dart:convert';
    import 'dart:io';
    ​
    import 'package:http/http.dart' as http;
    ​
    import '../model/summary.dart';
    ​
    Future<Summary> getRandomArticleSummary() async {
      final Uri url = Uri.https(
        'en.wikipedia.org',
        '/api/rest_v1/page/random/summary',
      );
      final http.Response response = await http.get(url);
      if (response.statusCode == 200) {
        final Map<String, Object?> jsonData =
            jsonDecode(response.body) as Map<String, Object?>;
        return Summary.fromJson(jsonData);
      } else {
        throw HttpException(
          '[WikipediaApiClient.getRandomArticleSummary] '
          'statusCode=${response.statusCode}, body=${response.body}',
        );
      }
    }
    ​
    Future<Summary> getArticleSummaryByTitle(String articleTitle) async {
      final Uri url = Uri.https(
        'en.wikipedia.org',
        '/api/rest_v1/page/summary/$articleTitle',
      );
      final http.Response response = await http.get(url);
      if (response.statusCode == 200) {
        final Map<String, Object?> jsonData =
            jsonDecode(response.body) as Map<String, Object?>;
        return Summary.fromJson(jsonData);
      } else {
        throw HttpException(
          '[WikipediaApiClient.getArticleSummaryByTitle] '
          'statusCode=${response.statusCode}, body=${response.body}',
        );
      }
    }
    

    This code defines two functions, getRandomArticleSummary and getArticleSummaryByTitle, that build on the basic HTTP request you wrote in Chapter 3:

    • getRandomArticleSummary and getArticleSummaryByTitle: Fetch a random article summary or a specific summary by interpolating articleTitle into the endpoint path.
    • Typed JSON parsing: Instead of returning a raw JSON string, both functions decode response.body with jsonDecode and pass the map to Summary.fromJson to return a strongly typed Summary object.
    • Explicit failure handling: When response.statusCode isn't 200, the functions throw an HttpException (from dart:io) rather than returning an error string, so callers can catch and handle failed requests with try/catch.
  4. Next create the file wikipedia/lib/src/api/search.dart.

  5. Add the following code to wikipedia/lib/src/api/search.dart:

    wikipedia/lib/src/api/search.dart
    dart
    import 'dart:convert';
    import 'dart:io';
    ​
    import 'package:http/http.dart' as http;
    ​
    import '../model/search_results.dart';
    ​
    Future<SearchResults> search(String searchTerm) async {
      final Uri url = Uri.https(
        'en.wikipedia.org',
        '/w/api.php',
        <String, Object?>{
          'action': 'opensearch',
          'format': 'json',
          'search': searchTerm,
        },
      );
      final http.Response response = await http.get(url);
      if (response.statusCode == 200) {
        final List<Object?> jsonData =
            jsonDecode(response.body) as List<Object?>;
        return SearchResults.fromJson(jsonData);
      } else {
        throw HttpException(
          '[WikipediaApiClient.search] '
          'statusCode=${response.statusCode}, '
          'body=${response.body}',
        );
      }
    }
    

    This code defines the search function, which queries Wikipedia's opensearch endpoint and returns a SearchResults object:

    • Query parameters: Uri.https accepts an optional third argument—a Map of query parameters (action, format, and search). Dart automatically formats these key-value pairs onto the URL and URL-encodes special characters like spaces in searchTerm.
    • List decoding: Because the opensearch endpoint returns a top-level JSON array, jsonDecode(response.body) is cast to List<Object?> before passing it to SearchResults.fromJson.
  6. Create the file wikipedia/lib/src/api/get_article.dart.

  7. Add the following code to wikipedia/lib/src/api/get_article.dart:

    wikipedia/lib/src/api/get_article.dart
    dart
    import 'dart:convert';
    import 'dart:io';
    ​
    import 'package:http/http.dart' as http;
    ​
    import '../model/article.dart';
    ​
    Future<List<Article>> getArticleByTitle(String title) async {
      final Uri url = Uri.https(
        'en.wikipedia.org',
        '/w/api.php',
        <String, Object?>{
          // order matters - explaintext must come after prop
          'action': 'query',
          'format': 'json',
          'titles': title.trim(),
          'prop': 'extracts',
          'explaintext': '',
        },
      );
      final http.Response response = await http.get(url);
      if (response.statusCode == 200) {
        final Map<String, Object?> jsonData =
            jsonDecode(response.body) as Map<String, Object?>;
        return Article.listFromJson(jsonData);
      } else {
        throw HttpException(
          '[WikipediaApiClient.getArticleByTitle] '
          'statusCode=${response.statusCode}, '
          'body=${response.body}',
        );
      }
    }
    

    This code defines getArticleByTitle, which passes query parameters to /w/api.php (using title.trim() to strip accidental leading or trailing whitespace) and parses the response into a List<Article> using Article.listFromJson.

Task 3: Export the API functions

#

Now that you've created the API functions, export them and your existing models from the wikipedia library so that the cli package can import and use them.

  1. Open the wikipedia/lib/wikipedia.dart file.

  2. Replace the generated placeholder code in the file with the following export statements:

    wikipedia/lib/wikipedia.dart
    dart
    export 'src/api/get_article.dart';
    export 'src/api/search.dart';
    export 'src/api/summary.dart';
    export 'src/model/article.dart';
    export 'src/model/search_results.dart';
    export 'src/model/summary.dart';
    export 'src/model/title_set.dart';
    

    These export statements make the API functions and models available to other packages that depend on the wikipedia package.

Task 4: Verify with tests

#

Now that you've implemented the API functions and updated the package dependencies, run the tests you created in the previous chapter to confirm that your changes haven't broken existing functionality in wikipedia.

  1. Open your terminal and navigate to the wikipedia/test directory.

  2. Remove the default test file by running rm wikipedia_test.dart (on macOS or Linux) or del wikipedia_test.dart (on Windows). dart create generated this file automatically to test the placeholder code you just replaced, so your project no longer needs it.

  3. Navigate back to the wikipedia directory.

  4. Run dart test.

    You'll see output similar to the following, confirming that all your model tests pass:

    bash
    00:02 +3: All tests passed!
    

    This confirms that the wikipedia package is working as expected.

Review

#

What you accomplished

Here's a summary of what you built and learned in this lesson.
Constructed complex URIs with query parameters

You used Uri.https() with a query parameter map to construct API URLs. This approach properly encodes special characters and handles complex query parameter combinations.

Created a production-ready API client

You implemented API functions that check HTTP status codes, throw an HttpException on failed requests, and map raw JSON responses to typed Dart objects.

Exported functions and types for reuse

You added export statements in wikipedia.dart to expose both the API functions and data model types. This creates a public library that your cli package can import and use directly.

Quiz

#

Check your understanding

1 / 3
How do you construct a URL with query parameters using Uri.https?
  1. Pass them as a third argument map: Uri.https('api.com', '/search', {'q': 'dart'})

    That's right!

    The third parameter accepts a Map<String, dynamic> of query parameters. Dart handles URL encoding automatically.

  2. Append them to the path string: Uri.https('api.com', '/search?q=dart')

    Not quite.

    Query parameters in the path string work but aren't the cleanest approach.

  3. Use string concatenation: Uri.https('api.com', '/search') + '?q=dart'

    Not quite.

    You can't concatenate strings to Uri objects using +. Uri provides a different mechanism for adding query parameters.

  4. Call .addQueryParam('q', 'dart') on the Uri object.

    Not quite.

    Uri objects are immutable and don't have an addQueryParam method. Query parameters must be specified differently.

After calling http.get(url), how should you check if the request was successful?
  1. Check if response.statusCode == 200 (or another success code).

    That's right!

    HTTP status codes indicate success (200-299) or various failures (400s, 500s). Always check before processing the response body.

  2. Check if response.body is not empty.

    Not quite.

    An empty body could be valid (like a 204 No Content). The body content alone doesn't tell you if the request succeeded.

  3. Wrap the call in try/catch as successful requests don't throw.

    Not quite.

    HTTP errors (such as 404 and 500) don't throw exceptions by default. The request completes normally even when the server returns an error.

  4. Check if response.isSuccess returns true.

    Not quite.

    There's no isSuccess property on Response. You need to examine a different property of the response object.

When the Wikipedia API returns a non-200 status code, the lesson's API functions throw an HttpException instead of returning an error message string. Why is this a better practice for an API package?
  1. It separates failure handling from valid data, letting functions return typed models (like Summary) while callers handle errors with try/catch.

    That's right!

    Returning an error string doesn't fit a return type like Future<Summary> and risks treating error text as article data. Throwing an HttpException signals failure explicitly so calling code can catch and handle it.

  2. Because http.get crashes the Dart runtime if you don't throw an exception on non-200 status codes.

    Not quite.

    http.get completes normally with a Response object even for 404 or 500 status codes. Throwing HttpException is a deliberate design choice, not a runtime requirement.

  3. Throwing HttpException automatically retries the failed network request up to three times.

    Not quite.

    Throwing an exception stops execution of the function and propagates the failure to the caller; it doesn't retry the request.

  4. Functions marked async aren't allowed to return error strings when a network request fails.

    Not quite.

    An async function can return any declared type (such as Future<String>, as in Chapter 3). Throwing an exception is preferred for type safety and structured error handling, not syntax rules.

Next lesson

#

In the next lesson, you'll complete your CLI application by integrating the wikipedia package commands with the cli package and adding logging for debugging and error monitoring.