# A Simple API Client

Wrap an API in a client class, the way a DAO wraps a table. It's given an HttpClient, has one async method per endpoint, and turns 404 into null or false, so the rest of the program never sees a URL, a status code or JSON.

Journeyman · C# · REST API · Updated November 15, 2026

By Gregor Dzierzon

## After this lesson you can

- Wrap an API's endpoints in a client class with one async method each, turning 404 into null or false

## Key takeaways

- A client class wraps an API the way a DAO wraps a table: one async method per endpoint, plain objects in and out.
- `CategoryClient` turns a `404` into `null` or `false`; for anything else that isn't a success, `EnsureSuccessStatusCode()` throws for the caller to catch.
- The client asks for its `HttpClient` in the constructor, so the program can share one and a test can hand it a fake.
- Every URL and status code stays inside the client class, so if the API's addresses change, that's the one class to fix.

Calling `HttpClient` all over a program spreads URLs, status codes and JSON everywhere. You solved the same problem with databases: SQL lives in the DAO, and the rest of the program calls `GetById(8)`. An API deserves the same: a **client class** with one method per endpoint.

## The CategoryClient

```csharp
using System.Net;
using System.Net.Http.Json;

public class CategoryClient
{
    private readonly HttpClient client;

    public CategoryClient(HttpClient client)
    {
        this.client = client;
    }

    public async Task<List<Category>> GetAllAsync()
    {
        List<Category>? categories = await client.GetFromJsonAsync<List<Category>>("api/categories");
        return categories ?? new List<Category>();
    }

    public async Task<Category?> GetByIdAsync(int categoryId)
    {
        HttpResponseMessage response = await client.GetAsync($"api/categories/{categoryId}");
        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return null;
        }
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<Category>();
    }

    public async Task<Category> AddAsync(Category category)
    {
        HttpResponseMessage response = await client.PostAsJsonAsync("api/categories", category);
        response.EnsureSuccessStatusCode();
        return (await response.Content.ReadFromJsonAsync<Category>())!;
    }

    public async Task<Category?> UpdateAsync(Category category)
    {
        HttpResponseMessage response = await client.PutAsJsonAsync($"api/categories/{category.CategoryId}", category);
        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return null;
        }
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<Category>();
    }

    public async Task<bool> DeleteAsync(int categoryId)
    {
        HttpResponseMessage response = await client.DeleteAsync($"api/categories/{categoryId}");
        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return false;
        }
        response.EnsureSuccessStatusCode();
        return true;
    }
}
```

Look how much it looks like `ICategoryDao` from the API: the same five methods, the same `null` for a missing category, from `GetByIdAsync` and `UpdateAsync`, and the same `bool` for "was there anything to delete". The program using it can't tell whether the categories come from a database or across the network. That's **encapsulation**: the class hides how it does its job.

How each status is handled is a choice the client class makes once:

| The API answers | The method |
|---|---|
| `200`, `201`, `204` | Returns the data, or `true` |
| `404` | Returns `null` or `false`: an expected answer |
| Anything else, such as `400` or `500` | `EnsureSuccessStatusCode()` throws an `HttpRequestException`, for the caller to catch |

## It asks for its HttpClient

`CategoryClient` doesn't create its `HttpClient`; it asks for one in its constructor. That's dependency injection again, and it pays off twice:

- the program creates **one** `HttpClient`, with the base address, and shares it;
- a test can hand the client an `HttpClient` that answers from a fake, with no API running. The exercise's tests do exactly that.

## Using it

```csharp
using System.Net;
using System.Net.Http.Json;

using HttpClient http = new HttpClient { BaseAddress = new Uri("http://localhost:5179/") };
CategoryClient categories = new CategoryClient(http);

try
{
    foreach (Category category in await categories.GetAllAsync())
    {
        Console.WriteLine($"{category.CategoryId}. {category.CategoryName}");
    }

    Category? missing = await categories.GetByIdAsync(300);
    Console.WriteLine(missing == null ? "No category 300" : missing.CategoryName);

    Category snacks = await categories.AddAsync(new Category { CategoryName = "Snacks" });
    Console.WriteLine($"Deleted the new one: {await categories.DeleteAsync(snacks.CategoryId)}");
    Console.WriteLine($"Deleted it again: {await categories.DeleteAsync(snacks.CategoryId)}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"The categories API had a problem: {ex.Message}");
}

public class Category
{
    public int CategoryId { get; set; }
    public string CategoryName { get; set; } = "";
    public string? Description { get; set; }
}

public class CategoryClient
{
    private readonly HttpClient client;

    public CategoryClient(HttpClient client)
    {
        this.client = client;
    }

    public async Task<List<Category>> GetAllAsync()
    {
        List<Category>? categories = await client.GetFromJsonAsync<List<Category>>("api/categories");
        return categories ?? new List<Category>();
    }

    public async Task<Category?> GetByIdAsync(int categoryId)
    {
        HttpResponseMessage response = await client.GetAsync($"api/categories/{categoryId}");
        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return null;
        }
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<Category>();
    }

    public async Task<Category> AddAsync(Category category)
    {
        HttpResponseMessage response = await client.PostAsJsonAsync("api/categories", category);
        response.EnsureSuccessStatusCode();
        return (await response.Content.ReadFromJsonAsync<Category>())!;
    }

    public async Task<bool> DeleteAsync(int categoryId)
    {
        HttpResponseMessage response = await client.DeleteAsync($"api/categories/{categoryId}");
        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return false;
        }
        response.EnsureSuccessStatusCode();
        return true;
    }
}
```

```text
1. Beverages
2. Condiments
3. Confections
4. Dairy Products
5. Grains/Cereals
6. Meat/Poultry
7. Produce
8. Seafood
No category 300
Deleted the new one: True
Deleted it again: False
```

The program reads like it's using a list of categories in memory. Every URL and status code is in `CategoryClient`, and if the API's addresses change, that's the one class to fix.

## Do it: decide what a DELETE's answer means

`CategoryClient.DeleteAsync` sends a `DELETE`, then decides what the API's answer means for the program. Write that decision as a method of its own.

The practice box has no network, so `Program.cs` has small stand-ins at the bottom for .NET's `HttpResponseMessage`, `HttpStatusCode` and `HttpRequestException`, with the same names and the parts this lesson uses. Leave them as they are. The tests make each response themselves: `new HttpResponseMessage(HttpStatusCode.NoContent)` is a response whose status is `204 No Content`.

The method gets one value:

- `response`: the API's answer to a `DELETE`, an `HttpResponseMessage`.

Each answer means one thing:

| The API answers | It means | `WasDeleted` |
|---|---|---|
| A success: any 2xx code, such as `204 No Content` | The category was deleted | returns `true` |
| `404 Not Found` | There was nothing to delete: an expected answer | returns `false` |
| Anything else, such as `500` | A problem the caller must hear about | throws an `HttpRequestException` |

For example, deleting a category that's already gone gets a `404`:

```csharp
HttpResponseMessage response = new HttpResponseMessage(HttpStatusCode.NotFound);
bool deleted = WasDeleted(response);
```

`deleted` is `false`.

**Your job:** write the method `bool WasDeleted(HttpResponseMessage response)`.

- When the status is `404`, return `false`.
- When the status is a success (any 2xx code), return `true`.
- For any other status, throw an `HttpRequestException`. `response.EnsureSuccessStatusCode()` throws exactly that.

Practiced live on the lesson page: write the C# right there and check it.

## Check yourself

1 question to try on the lesson page.

## So what

A client class is a DAO for an API: one method per endpoint, plain objects in and out, and the HTTP details hidden inside. Ask for the `HttpClient` in the constructor, and both the program and the tests can give it what they need.

## Key terms

- [API Client](https://www.ask-codey.com/glossary/api-client)
- [Encapsulation](https://www.ask-codey.com/glossary/encapsulation-c-sharp)
- [Dependency Injection](https://www.ask-codey.com/glossary/dependency-injection)

## Cheat sheets

- [A Simple API Client](https://www.ask-codey.com/cheat-sheets/calling-apis-with-httpclient-using-a-simple-http-client-cheat-sheet)

Source: https://www.ask-codey.com/lessons/calling-apis-with-httpclient-using-a-simple-http-client
