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 Redis-backed output caching. All public endpoints are cached server-side with automatic invalidation when content is modified through the dashboard or API. This means:

• First request after a content change hits the database
• Subsequent requests within the cache window are served directly from Redis
• Content changes (publishing, editing, deleting posts, updating tags/categories) immediately invalidate the relevant server cache entries

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.