📝 Lesson 5.1: Calling Web APIs with HttpClient

What Is a Web API?

A web API is a service on the internet that programs (not people) can call to get or send data. Your code sends an HTTP request to a URL; the server sends back an HTTP response, very often as JSON.

In .NET, the class for making these calls is HttpClient (in System.Net.Http). Every method is asynchronous — network calls are exactly the slow, waiting work that async/await was made for.

Your First Request

The simplest call fetches a URL's content as a string. Since it's async, we await it (Lesson 4.3):

using System.Net.Http;

HttpClient client = new HttpClient();

string json = await client.GetStringAsync("https://api.example.com/products");
Console.WriteLine(json);   // the raw JSON text the server returned

That gives you the response body as text. You could then hand it to JsonSerializer.Deserialize from Lesson 4.2 — but there's a shortcut that does both steps at once, coming next.

JSON Straight into Objects

The method GetFromJsonAsync<T> (from System.Net.Http.Json) fetches a URL and deserializes the JSON response into your type in one call — combining Lessons 4.2 and 4.3 beautifully:

using System.Net.Http.Json;

record Todo(int Id, int UserId, string Title, bool Completed);

HttpClient client = new HttpClient();

Todo? todo = await client.GetFromJsonAsync<Todo>(
    "https://jsonplaceholder.typicode.com/todos/1");

Console.WriteLine($"{todo?.Id}: {todo?.Title} (done: {todo?.Completed})");

Fetching a whole list is just as easy — deserialize into a List<T>:

List<Todo>? todos = await client.GetFromJsonAsync<List<Todo>>(
    "https://jsonplaceholder.typicode.com/todos");

Console.WriteLine($"Fetched {todos?.Count} todos.");

// Now use LINQ (Lesson 2.3) on live data!
var completed = todos?.Where(t => t.Completed).Count();
Console.WriteLine($"{completed} are completed.");

Status Codes & Errors

Every HTTP response carries a status code that says how it went. You'll want to recognize the common ranges:

For finer control, use GetAsync, which returns a response object you can inspect before reading the body:

HttpResponseMessage response = await client.GetAsync(url);

if (response.IsSuccessStatusCode)   // true for any 2xx
{
    string body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}
else
{
    Console.WriteLine($"Request failed: {(int)response.StatusCode} {response.StatusCode}");
}

Two kinds of things can go wrong, and robust code handles both (using Lesson 1.1's exception skills):

try
{
    Todo? todo = await client.GetFromJsonAsync<Todo>(url);
    Console.WriteLine(todo?.Title);
}
catch (HttpRequestException ex)     // network failure, DNS, non-success status
{
    Console.WriteLine($"Network error: {ex.Message}");
}
catch (TaskCanceledException)       // timeout
{
    Console.WriteLine("The request timed out.");
}

Reusing HttpClient

Here's a crucial real-world detail. Although HttpClient is IDisposable, you should not create a new one for every request. Doing so in a loop can exhaust the operating system's network connections (a well-known bug called socket exhaustion).

// ❌ A new client per request — can exhaust sockets
foreach (var url in urls)
{
    using var client = new HttpClient();   // BAD in a loop
    var data = await client.GetStringAsync(url);
}

// ✅ One shared client, reused
HttpClient client = new HttpClient();

foreach (var url in urls)
{
    var data = await client.GetStringAsync(url);
}

HttpClient client = new HttpClient
{
    BaseAddress = new Uri("https://jsonplaceholder.typicode.com/"),
    Timeout = TimeSpan.FromSeconds(10)
};

// Then use relative paths:
var todo = await client.GetFromJsonAsync<Todo>("todos/1");

Exercise & Quiz

using System.Net.Http.Json;

record Todo(int Id, int UserId, string Title, bool Completed);

HttpClient client = new HttpClient();

// TODO: try/catch; fetch List<Todo>; print count, completed count, first incomplete title

using System.Net.Http.Json;

record Todo(int Id, int UserId, string Title, bool Completed);

HttpClient client = new HttpClient();
string url = "https://jsonplaceholder.typicode.com/todos";

try
{
    List<Todo>? todos = await client.GetFromJsonAsync<List<Todo>>(url);

    if (todos is null || todos.Count == 0)
    {
        Console.WriteLine("No todos returned.");
        return;
    }

    Console.WriteLine($"Total todos: {todos.Count}");
    Console.WriteLine($"Completed: {todos.Count(t => t.Completed)}");

    Todo? firstOpen = todos.FirstOrDefault(t => !t.Completed);
    Console.WriteLine($"First incomplete: {firstOpen?.Title ?? "(none)"}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Could not reach the API: {ex.Message}");
}

Total todos: 200
Completed: 90
First incomplete: delectus aut autem

Summary

📚 Additional Resources

• Make HTTP requests with HttpClient — Microsoft Docs
• Deserialize JSON (incl. from HttpClient)
• JSONPlaceholder — free fake API for testing

🚀 What's Next?

Your code now talks to the wider world. Before the capstone, we'll make sure it stays correct as it grows. In Lesson 5.2: Unit Testing, you'll write automated tests that prove your code works — and keep it working.