Caching

Overview

The Postnomic Client SDK includes an optional in-memory caching layer that reduces the number of API calls your application makes. When enabled, read operations (blog info, posts, tags, categories, authors) are served from a local cache, significantly improving page load times and reducing load on the Postnomic API.

Caching is disabled by default and must be explicitly opted into via configuration. No external infrastructure (such as Redis) is required — caching uses the built-in .NET IMemoryCache.

Enabling Caching

Inline Configuration

builder.Services.AddPostnomicBlog(options =>
{
    options.BaseUrl  = "https://api.postnomic.com";
    options.ApiKey   = "pk_your_blog_key_here";
    options.BlogSlug = "my-dev-blog";
    options.Cache    = new PostnomicCacheOptions { Enabled = true };
});

Configuration from appsettings.json

{
  "Postnomic": {
    "BaseUrl": "https://api.postnomic.com",
    "ApiKey": "pk_your_blog_key_here",
    "BlogSlug": "my-dev-blog",
    "Cache": {
      "Enabled": true,
      "MetadataDuration": "00:05:00",
      "PostListDuration": "00:02:00",
      "PostDetailDuration": "00:05:00",
      "PopularPostsDuration": "00:10:00"
    }
  }
}

Cache Durations

Each type of data has its own configurable cache duration. Values are specified as TimeSpan strings (e.g., "00:05:00" for 5 minutes).

What Is Cached

Cached (read operations)

• GetBlogAsync — blog name, description, layout
• GetTagsAsync — all tags with post counts
• GetCategoriesAsync — all categories with post counts
• GetAuthorsAsync — author list with post counts
• GetAuthorProfileAsync — full author profile and recent posts
• GetPostsAsync — paginated post listings (each page/filter combination is cached separately)
• GetPostAsync — individual post content including approved comments
• GetTopCommentedPostsAsync — posts ranked by comment count
• GetMostReadPostsAsync — posts ranked by page views

Not Cached (write operations)

• CreateCommentAsync — always hits the API; automatically invalidates the cached post detail
• RecordPageViewAsync — analytics tracking, always passes through
• UpdateReadDurationAsync — analytics tracking, always passes through

Cache Invalidation

Automatic Invalidation

When a visitor submits a comment via CreateCommentAsync, the cached detail for that post is automatically cleared so the next page load shows the new comment.

Manual Invalidation

For scenarios where you need to programmatically clear cached data, inject IPostnomicCacheControl from DI:

public class MyService
{
    private readonly IPostnomicCacheControl _cacheControl;

    public MyService(IPostnomicCacheControl cacheControl)
    {
        _cacheControl = cacheControl;
    }

    public void ClearPostCache(string postSlug)
    {
        _cacheControl.InvalidatePost(postSlug);
    }

    public void ClearMetadata()
    {
        _cacheControl.InvalidateMetadata();
    }

    public void ClearEverything()
    {
        _cacheControl.InvalidateAll();
    }
}

When caching is disabled, IPostnomicCacheControl resolves to a no-op implementation, so your code does not need conditional checks.

Server-Side Caching

In addition to client-side caching, the Postnomic API itself uses ASP.NET Core output caching. It is backed by the framework's in-memory store — an earlier Redis-backed setup was removed — so the server cache lives per API replica. The public endpoints are cached with these durations:

Content changes (publishing, editing, deleting posts, updating tags or categories) evict the relevant cache entries by blog tag. Because the cache is per replica, eviction only clears the replica that handled the mutation. The API runs up to three replicas, so other replicas keep serving the previous response until its own duration expires — at most 5 minutes for the longest content policy. Expect a short window after a change during which some readers still see the old content.

Requests from authenticated users bypass the server cache entirely.

The combination of server-side and client-side caching provides two layers of protection against unnecessary database queries and network round-trips.

Performance Recommendations

• Enable caching for production deployments — the default durations provide a good balance between freshness and performance.
• Lower PostListDuration if your blog publishes frequently and readers expect to see new posts immediately.
• Increase PopularPostsDuration to 30+ minutes, since popular post rankings change slowly.
• Keep MetadataDuration at 5 minutes — tags and categories rarely change, so longer caching is safe, but 5 minutes ensures new tags appear within a reasonable time.