Skip to content
Tutorials Center
My learning

Topics

Lesson 49 of 52 ยท Projects

Project: Blog API with Pagination and Caching

Build a layered blog API in ASP.NET Core: filtering, paging, ETags with conditional requests, output caching with tag eviction, and a tiny in-process test suite.

Most real APIs spend their life answering one question: "give me a list of things, but not all of them, and please do it fast." This project builds a small blog API around exactly that. You will split the code into layers, filter and page a collection, protect clients from re-downloading unchanged data with ETags, and let the server remember popular answers with output caching. At the end, a tiny test suite runs against a real Kestrel server to prove it all works.

The project pulls together ideas from earlier lessons: minimal API endpoints, route groups, parameter binding, dependency injection and caching. If any step feels fast, follow the link and refresh your memory first.

The plan

We keep everything in one file because the runner compiles a single file, but we still separate responsibilities. In a real solution each box below would be its own file or folder.

flowchart LR
    C["Client"] --> E["Endpoints<br/>HTTP in, HTTP out"]
    E --> S["PostService<br/>filtering and paging rules"]
    S --> R["IPostRepository<br/>data access"]
    R --> D[("In-memory list")]
    E -.-> K["Output cache<br/>and ETag check"]

Layers of the blog API: endpoints talk HTTP, the service owns the rules, the repository owns the data.

  • Endpoints translate between HTTP and your code: parse the query string, choose status codes, set headers.
  • Service holds the rules: how filtering works, the maximum page size, what counts as a match.
  • Repository hides where posts live. Today it is a list; tomorrow it could be EF Core. Only the repository changes.

Because the service depends on IPostRepository, not on a concrete class, swapping the store (or faking it in a test) never touches the rules.

Step 1: layers, filtering and paging

Start with the models. Records are ideal here: short, immutable and comparable (see DTOs, records and mapping).

PostQuery describes what the client may ask for. PagedResult<T> is the envelope we return, so clients know how many results exist in total and whether another page follows.

A few design rules we follow:

  1. Always page. An endpoint that returns "everything" works with ten rows and fails with ten million.
  2. Clamp, do not trust. A client asking for pageSize=100000 gets the maximum, not a crash.
  3. Order deterministically. Paging needs a stable order; without it, the same row can appear on two pages. We sort by date descending, then by id.
C# Layered posts endpoint with filtering and paging

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Notice how thin the endpoints are: the list endpoint is one line because the service does the work. When the paging rules change, you edit PostService and the endpoints stay put.

Also notice the Results<Ok<Post>, NotFound> return type. It documents both outcomes in the signature, which helps tools such as OpenAPI generators.

For very large tables, Skip and Take (offset paging) gets slower the deeper you go, and rows can shift between requests when data changes. Keyset paging ("give me the 5 posts older than the last one I saw") avoids both problems. Offset paging is fine for most blogs; reach for keyset when pages go thousands deep.

Step 2: ETags and conditional requests

A client that already has page 1 should not download it again if nothing changed. HTTP solves this with an ETag: a short fingerprint of the response. The server sends it in the ETag header. Next time, the client sends it back in If-None-Match. If it still matches, the server replies 304 Not Modified with no body, saving bandwidth even though the server still did some work to compute the fingerprint.

The same idea works in the other direction for writes. A client sends If-Match with the ETag it last saw, and the server refuses with 412 Precondition Failed if somebody else changed the resource in the meantime. That is optimistic concurrency over plain HTTP.

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: GET /posts/1
    S-->>C: 200 + ETag "abc"
    C->>S: GET /posts/1 (If-None-Match "abc")
    S-->>C: 304 Not Modified (no body)
    C->>S: PUT /posts/1 (If-Match "abc")
    S-->>C: 200 + new ETag "def"
    C->>S: PUT /posts/1 (If-Match "abc")
    S-->>C: 412 Precondition Failed

ETags let clients skip unchanged downloads and detect conflicting edits.

We compute the tag by hashing the JSON of the resource, then wrap it in double quotes as HTTP requires. Any stable hash works; we take the first eight bytes of SHA-256.

C# ETag, 304 and If-Match

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The small EtagResult wrapper is a custom IResult: it adds the header, then lets the normal JSON result do its job. Wrapping results this way keeps header logic out of every handler.

A few cautions when you use ETags in your own APIs:

  • Hash what the client actually sees. If two different JSON bodies share an ETag, clients will show stale data.
  • An ETag is not a security feature. It is a fingerprint, so do not put secrets in it.
  • A 304 response must not contain a body, and it should still carry the ETag header. For our demo the status alone is enough to show the idea.

Step 3: output caching

ETags save bandwidth, but the server still runs the handler each time. Output caching saves the work too: the server stores the finished response and replays it for matching requests. It is configured with a policy that says how long entries live and which parts of the request make two requests "different" (the cache key).

Two details matter for a paged list:

  1. Vary by query. /posts?page=1 and /posts?page=2 must be cached separately, so the policy lists the query keys that vary the entry. Without that, every URL would share one entry (or none).
  2. Tag and evict. When a new post is published, the cached lists are wrong. Tagging entries lets you evict all of them with one call instead of waiting for them to expire.

The demo counts how many times the handler really runs, so you can watch the cache work.

C# Output caching with tag eviction

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Five requests to the list ran the handler only twice, and the new post shows up immediately after the eviction. That is the usual recipe: cache aggressively, evict by tag when you write.

Never output-cache responses that depend on who is asking (a user's dashboard, anything behind authentication) unless the policy varies by user. By default the framework refuses to cache requests that carry an Authorization header or set cookies, precisely to prevent leaking one person's data to another.

Step 4: tests that prove it

A project is only done when you can show it works. The final program assembles every piece: layered services, paging, ETags and output caching. Then a tiny test runner starts the server and checks behavior through real HTTP calls. xUnit would be the tool in a real solution (see Testing ASP.NET Core apps); here a ten-line helper prints PASS or FAIL.

A good API test asserts behavior a client can observe: status codes, headers and the shape of the body. It does not peek at private fields.

C# The finished blog API with its tests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Look at what the tests did not do: they never created the object graph by hand. They used the same HTTP surface a real client uses, so a regression in routing, binding, caching or serialization is caught too.

Where to go from here

You now have the skeleton of a production-style list API. Natural next steps, each one a lesson or two away:

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the project hide data access behind IPostRepository?

    Depending on an abstraction lets you swap the in-memory list for a database, or a fake in tests, without touching the rules or the HTTP code.
  2. 2. A client sends If-None-Match with the current ETag. What should the server return?

    If-None-Match means 'send it only if it changed'. When the tag still matches, 304 tells the client to keep its copy.
  3. 3. What is the purpose of SetVaryByQuery("page", "tag") in an output cache policy?

    The query keys become part of the cache key, so page 1 and page 2 do not overwrite each other's entries.
  4. 4. Why tag cache entries and evict by tag after a write?

    After a new post is published, all cached lists are out of date. Evicting by tag clears them together while unrelated entries stay cached.
  5. 5. Which paging behavior is a good defense against abuse?

    The server decides the limits. Clamping keeps a single request from loading the whole table, and a deterministic sort keeps pages consistent.

Summary

  • Split the API into endpoints (HTTP), a service (rules) and a repository (data) so each layer can change alone.
  • Always page list endpoints, clamp client-supplied sizes and sort deterministically.
  • ETags plus If-None-Match give cheap 304 responses; If-Match gives optimistic concurrency with 412.
  • Output caching replays whole responses; vary by the query keys that matter and evict by tag when data changes.
  • Never cache user-specific responses without varying by user.
  • Test through real HTTP calls so routing, binding and caching are covered too.

Next: Practice Exercises with Solutions