Calling an API

Every call in this course so far has been a method on an object in the same process. It returned immediately, and if it failed, it failed in a way you wrote. An API call is different in two ways that the person using your screen can see: it takes time, and it can fail for reasons that have nothing to do with your code.

A component that ignores either of those tells the reader something untrue. It shows an empty list while data is on its way, so the reader concludes there are no employees. It shows the same empty list when the request failed, so the reader concludes the same thing and never finds out otherwise.

Being honest about it means four outcomes on screen, not one. The request is in flight. The request failed. The request worked and there is nothing to show. The request worked and here is the data. Only the last one usually gets written, and the other three are where the reader's trust is won or lost.

// Program.cs
builder.Services.AddHttpClient<EmployeeApiClient>(client =>
{
    client.BaseAddress = new Uri(builder.Configuration["EmployeeApi:BaseAddress"]!);
    client.Timeout = TimeSpan.FromSeconds(10);
});

// Services/EmployeeApiClient.cs
public sealed class EmployeeApiClient(HttpClient http)
{
    public async Task<List<Employee>> SearchAsync(string? term, CancellationToken token)
    {
        var url = string.IsNullOrWhiteSpace(term)
            ? "api/employees"
            : "api/employees?name=" + Uri.EscapeDataString(term);

        using var response = await http.GetAsync(url, token);
        response.EnsureSuccessStatusCode();

        return await response.Content.ReadFromJsonAsync<List<Employee>>(token) ?? [];
    }
}

• AddHttpClient registers a typed client: the framework builds the HttpClient, applies this configuration, and hands it to the constructor. The class never creates one itself.
• IHttpClientFactory is what sits behind that. It pools and rotates the underlying handlers, which avoids two opposite failures — creating a client per call exhausts sockets under load, and keeping one forever means a DNS change is never noticed.
• The base address and the timeout are set once, in one place. Ten seconds is a decision; the default is 100, which is far longer than anyone waits before deciding your application is broken.
• Uri.EscapeDataString on anything a person typed. A search for "R&D" otherwise ends the query string early and the API sees a different search than the one requested.
• EnsureSuccessStatusCode turns a 4xx or 5xx into an exception. That suits this screen, because it treats every failure the same way. When a 404 means something specific to you, check StatusCode instead of throwing.
• ?? [] means a body of null becomes an empty list rather than a null reference three lines later in the markup.
• Every method takes a CancellationToken and passes it on. A token that is accepted and then ignored is worse than no token, because the caller believes the work can be abandoned when it cannot.

@page "/employees"
@rendermode InteractiveServer
@inject EmployeeApiClient Api
@inject ILogger<EmployeeSearch> Logger
@implements IDisposable

<h1>Employees</h1>

<label for="employee-search">Search by name</label>
<input id="employee-search" @bind="term" @bind:after="LoadAsync" />

@if (isLoading)
{
    <p role="status">Loading employees…</p>
}
else if (loadFailed)
{
    <div role="alert">
        <p>The employee list could not be loaded.</p>
        <button type="button" @onclick="LoadAsync">Try again</button>
    </div>
}
else if (employees.Count == 0)
{
    <p>No employees match that search.</p>
}
else
{
    <ul>
        @foreach (var employee in employees)
        {
            <li @key="employee.Id">@employee.Name — @employee.Department</li>
        }
    </ul>
}

• Four branches, checked in the order the outcomes can occur. Loading first, because until the request finishes nothing else is known yet.
• role="status" announces the wait to a screen reader. A spinner is an empty region to someone who cannot see it, and "loading" is the one message people most need while nothing is happening.
• role="alert" on the failure is announced as soon as it appears, and the branch offers a way forward. An error message with no action is a dead end, and the reader's only remaining option is to reload the page and lose their search.
• The empty branch is not a failure and must not look like one. "No employees match that search" and "the list could not be loaded" are different facts, and merging them sends people to the service desk about a system that is working.
• @bind:after runs a method after the binding has written the value back, so the search reloads without a separate handler. It does fire on every change event, which for a busy API is an argument for a debounce.
• employees starts as an empty list, so the loop cannot throw while the first request is in flight.
• @implements IDisposable is how this component cleans up an abandoned request, which the next section covers.

@code {
    private readonly CancellationTokenSource cts = new();

    private List<Employee> employees = [];
    private string term = "";
    private bool isLoading;
    private bool loadFailed;

    protected override Task OnInitializedAsync() => LoadAsync();

    private async Task LoadAsync()
    {
        isLoading = true;
        loadFailed = false;

        try
        {
            employees = await Api.SearchAsync(term, cts.Token);
        }
        catch (OperationCanceledException)
        {
            // The component is going away. There is nobody left to tell.
            return;
        }
        catch (Exception ex)
        {
            Logger.LogError(ex, "Loading the employee list failed for term {Term}", term);
            loadFailed = true;
        }
        finally
        {
            isLoading = false;
        }
    }

    public void Dispose()
    {
        cts.Cancel();
        cts.Dispose();
    }
}

• One CancellationTokenSource per component, cancelled in Dispose. When Blazor disposes the component — the reader navigated away, or a parent stopped rendering it — every request started with this token is asked to stop.
• Setting isLoading and clearing loadFailed at the top means a retry starts from a clean state instead of showing the previous error underneath a spinner.
• OperationCanceledException is caught separately and does nothing. It is not a failure, it is the outcome you asked for, and logging it fills your log with noise that looks like a problem.
• The general catch logs with detail and sets a flag. The flag is what the markup reads; the exception never reaches the reader.
• finally clears isLoading on every path, including the early return. Without it, one early return leaves a spinner on screen forever, and the reader waits for something that already finished.
• Because LoadAsync was invoked by the framework — a lifecycle method, a click, or @bind:after — Blazor re-renders when it finishes and again at each await. No StateHasChanged is needed here.
• Disposing the token source after cancelling it releases what it holds. In Blazor Server the circuit can be long-lived, so a component that leaks on every navigation leaks for hours.