You now know how to send bytes over HTTP and how JSON represents data — this lesson is where those two things meet.

In the previous lesson, you sent a GET request and got back raw text, then manually built a JSON string for a POST body. That works, but it's exactly the kind of repetitive, error-prone plumbing a good library should handle for you. You already know System.Text.Json can turn a C# object into JSON text and back (lesson 47) — HttpClient has extension methods that fuse that directly into the request/response pipeline, so you go straight from "call this API" to "here's my strongly-typed object," with the JSON step invisible in between.

In this lesson, you'll learn how to call a JSON REST API using GetFromJsonAsync and PostAsJsonAsync, how to deserialize responses directly into your own DTO classes, and how to handle the API returning something other than success.

What Is It?

The Simple Explanation

A DTO (Data Transfer Object) is a plain C# class whose only job is to mirror the shape of the JSON an API sends or expects — no behavior, just properties. The System.Net.Http.Json namespace adds extension methods directly onto HttpClient — GetFromJsonAsync<T> and PostAsJsonAsync among them — that combine "make the HTTP call" and "serialize/deserialize the JSON" into a single line, using a DTO as the target type.

The Technical Definition

GetFromJsonAsync<T>(string uri) sends a GET request, reads the response body, and deserializes it into an instance of T using System.Text.Json, all in one call. PostAsJsonAsync<T>(string uri, T value) does the reverse: serializes value to JSON, sets the content type to application/json, and sends it as a POST request body. Both return awaitable tasks and both throw on genuinely malformed responses, but — importantly — neither one throws just because the server returned a non-success status code like 404 or 500; that's something you still check yourself.

Why Does It Exist?

The Problem — Calling a JSON API Used to Be Repetitive Boilerplate

Every single call to a JSON API follows the same pattern: send the request, read the response body as a string, hand that string to JsonSerializer.Deserialize<T>, and (for a POST) do the reverse in the other direction — serialize an object, wrap it in StringContent with the right content type, then send it. Writing this out by hand every time is not just tedious; it's also an easy place to introduce small bugs — forgetting the content type header, forgetting to check the status before deserializing, forgetting to dispose a stream.

The Solution — Fuse the HTTP Call and the JSON Conversion

Because calling a JSON API and converting the payload are almost always done together, .NET provides extension methods that do both in one step, directly on HttpClient. This is exactly the same relationship as IHttpClientFactory to raw socket management: the underlying mechanism (an HTTP call, a JSON conversion) hasn't gone away — it's just no longer something you have to wire together by hand every single time.

Big Picture

var quote = await client.GetFromJsonAsync<PriceQuote>("quotes/latest");

quote.Symbol   // "AAPL"
quote.Price    // 231.50
quote.AsOfUtc  // 2026-08-30T14:03:00Z

Compare that to the manual approach from the previous lesson: GetAsync + ReadAsStringAsync + JsonSerializer.Deserialize<T>, written out as three separate steps every single time you need data from an API. GetFromJsonAsync<T> is those same three steps, fused into one call.

How It Works

public class PriceQuote
{
    public string Symbol { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public DateTime AsOfUtc { get; set; }
}

PriceQuote? quote = await client.GetFromJsonAsync<PriceQuote>("quotes/latest");

var response = await client.PostAsJsonAsync("orders", newOrder);
response.EnsureSuccessStatusCode();

Simple Example

public record WeatherForecastDto(string City, double TemperatureCelsius, string Summary);

public class WeatherClient(HttpClient httpClient)
{
    public async Task<WeatherForecastDto?> GetForecastAsync(string city)
    {
        var response = await httpClient.GetAsync($"forecast?city={Uri.EscapeDataString(city)}");

        if (!response.IsSuccessStatusCode)
        {
            return null; // caller decides how to handle "no forecast available"
        }

        return await response.Content.ReadFromJsonAsync<WeatherForecastDto>();
    }
}

// Registration
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddHttpClient<WeatherClient>(client =>
{
    client.BaseAddress = new Uri("https://api.weather.example.com/");
});

using var host = builder.Build();
var weatherClient = host.Services.GetRequiredService<WeatherClient>();

var forecast = await weatherClient.GetForecastAsync("Seattle");
if (forecast is not null)
{
    Console.WriteLine($"{forecast.City}: {forecast.TemperatureCelsius}°C, {forecast.Summary}");
}

Notice this example checks IsSuccessStatusCode before calling ReadFromJsonAsync<T> (the content-level equivalent of GetFromJsonAsync, useful once you already have an HttpResponseMessage in hand) — attempting to deserialize an error response's body as if it were a WeatherForecastDto would either throw a confusing deserialization exception or, worse, silently produce a mostly-empty, misleading object.

Real-World Example

A background notification worker calls a third-party SMS gateway: it POSTs a message request as JSON and reads back a typed result DTO — with explicit handling for the gateway rejecting the request (a 4xx, meaning the request itself was bad) versus the gateway being unavailable (a 5xx or network failure, meaning it might be worth retrying):

public record SendSmsRequest(string PhoneNumber, string Message);
public record SendSmsResult(bool Delivered, string MessageId);

public class SmsGatewayClient(HttpClient httpClient, ILogger<SmsGatewayClient> logger)
{
    public async Task<SendSmsResult?> SendAsync(SendSmsRequest request)
    {
        HttpResponseMessage response;
        try
        {
            response = await httpClient.PostAsJsonAsync("messages", request);
        }
        catch (HttpRequestException ex)
        {
            // Network-level failure — DNS, connection refused, TLS handshake, etc.
            logger.LogError(ex, "SMS gateway unreachable while sending to {PhoneNumber}", request.PhoneNumber);
            return null;
        }

        if (response.StatusCode is System.Net.HttpStatusCode.BadRequest)
        {
            // 400 — our request was malformed; retrying won't help, this needs a code fix
            logger.LogWarning("SMS gateway rejected the request for {PhoneNumber}: {Status}", request.PhoneNumber, response.StatusCode);
            return null;
        }

        if (!response.IsSuccessStatusCode)
        {
            // 5xx or similar — the gateway is having problems; this might succeed on retry
            logger.LogWarning("SMS gateway returned {Status} for {PhoneNumber}", response.StatusCode, request.PhoneNumber);
            return null;
        }

        return await response.Content.ReadFromJsonAsync<SendSmsResult>();
    }
}

Treating "the gateway said no" (a 400) and "the gateway is down" (a 500, or the request never even completed) as the exact same kind of failure would be a mistake — one is worth retrying, and one isn't. Distinguishing them requires actually inspecting the status code rather than only catching exceptions.

Analogy

Under the Hood

Common Confusion

"No exception was thrown, so the call must have succeeded" — not necessarily

This is the single most important thing to internalize about GetFromJsonAsync and PostAsJsonAsync: a 404 Not Found or a 500 Internal Server Error, by itself, does not throw. If you skip an explicit status check and just try to use the returned object, you may end up working with null, a partially-populated DTO, or (worse) an exception thrown later from an unrelated line of code that assumed the data was valid — far from where the real problem occurred.

A DTO is not the same thing as your domain model

It's tempting to reuse the same class for "the shape the API sends" and "the class my business logic actually works with," but APIs change their JSON shape over time, sometimes in ways that don't map cleanly onto how your application wants to think about the data. Keeping a dedicated, API-shaped DTO — and mapping it into your own domain type when needed — insulates your core logic from a third-party API's JSON quirks.

Common Mistakes

Mistake 1 — Assuming GetFromJsonAsync throws on a 404

Wrapping only a try/catch around GetFromJsonAsync<T> and assuming that's sufficient to catch "the resource wasn't found" — it isn't; a 404 with a JSON-shaped error body may deserialize without throwing anything at all, or may throw a confusing JsonException instead of a clear "not found" signal.

When you need to distinguish success from a specific status code, call GetAsync first, check response.StatusCode explicitly, and only then call ReadFromJsonAsync<T> on the content if the status indicates success.

Mistake 2 — Ignoring the nullable result

var quote = await client.GetFromJsonAsync<PriceQuote>(url); Console.WriteLine(quote.Price); — this compiles with a nullable-reference-types warning, and throws a NullReferenceException at runtime if the body was literally null or empty.

Treat the result as genuinely nullable: check if (quote is not null) before using it, or use the null-conditional operator where appropriate.

Mistake 3 — Treating "bad request" (4xx) and "server down" (5xx) identically

Catching everything into one generic "the API call failed" branch and retrying blindly — retrying a malformed request (400) just repeats the same failure; only a transient failure (like a 503 or a timeout) is actually worth retrying.

Branch on the status code (or category — 4xx vs 5xx) to decide whether retrying makes sense, exactly as shown in the SMS gateway example above.

When Should I Use It?

• Use GetFromJsonAsync/PostAsJsonAsync for the common case: you trust the endpoint to return either success with a well-formed body, or a status you don't need to inspect in detail.
• Drop down to GetAsync/PostAsync plus a manual ReadFromJsonAsync<T> call whenever you need to branch on the specific status code before deciding whether (or how) to deserialize the body — exactly the pattern used in both real-world examples in this lesson.
• Always define DTOs that mirror the external API's actual JSON shape, rather than reusing your internal domain classes directly for external calls.

Mental Model

Key Takeaway

Check Your Understanding

You've seen how GetFromJsonAsync and PostAsJsonAsync simplify calling a JSON API. Let's confirm you understand exactly what they do — and don't — guard against.

You now know how to call a JSON REST API from .NET, deserialize responses into DTOs, and correctly handle non-success status codes.

dotnetmadeeasy.com — Learn C# and .NET, the right way.