Recently, I’ve been thinking about how much responsibility we place on consumers when designing API contracts. One particular scenario that comes to mind is an application that evaluates callers to determine whether they qualify for a particular bucket.

These buckets could have limits on how many entries they can accept. The application accepts a collection of buckets to evaluate and returns whichever ones the caller qualifies for.

For instance, given this request:

{
  "qualifiedBuckets": [
    "male",
    "18-21"
  ]
}

The response might look something like this:

{
  "results": [
    "male"
  ]
}

In this scenario, the caller qualified for the male bucket, but the 18-21 bucket had already reached its designated limit.

At first glance, this seems straightforward enough. The application requested two buckets and received one, so we can infer that the caller didn’t qualify for the other.

However, this introduces a design flaw: the consuming application now has to compare the requested buckets against the results to determine what actually happened. Another consumer of the same API would have to implement that same logic.

This got me thinking about how we could improve the contract to make the results more explicit, rather than requiring consumers to infer the outcome.

Publishing

For our Blog API, we left off at CI/CD and deploying to Azure.

This post will be published using the new application, but it will not be the first. In fact, the previous blog post was the first official post that followed the entire create-and-publish workflow using the application.

Initially, I had the idea of using Git with a mounted drive to see what it would be like to manage Git directly through code. Codex pointed me toward a different resource: the Azure DevOps REST API.

This ended up being a much better fit. The repository already exists in Azure DevOps, so there is no reason for the application to manage a local repository, mounted storage, synchronization state, or the Git executable itself.

It also integrates nicely with the authentication model I already have in place. Since the application authenticates through Entra, I can inject a TokenCredential directly into the publisher:

public sealed class AzureDevOpsBlogPostPublisher(
    IHttpClientFactory httpClientFactory,
    TokenCredential credential,
    IBlogPostMarkdownRenderer markdownRenderer,
    IOptions<PublishingSettings> options) : IBlogPostPublisher
{ /* implementation */ }

The publisher can then request a token and attach it directly to the Azure DevOps request:

var token = await credential.GetTokenAsync(
    new TokenRequestContext([AzureDevOpsScope]),
    cancellationToken);

// other code

request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

Now, when we publish a post, the API commits the generated Markdown file directly to the repository.

If we need to remove a published post, the API simply sends another commit that deletes the Markdown file.

That gives us a fairly simple publication workflow at the API level.

Publishing Information

There was still one missing piece when I initially added publishing: updates.

I had not finished the update endpoint yet, and I made a couple of errors in the previous post.

To fix them, I had to open Cosmos DB, find the rendered content, manually update it, save it, delete the published version, and then republish it.

Obviously, that is not something I want to do repeatedly.

There was also a UI consideration. If we update an already published post, the application needs to know that the published version is now out of date and can be published again.

My initial prompt was:

we need to enhance publish information to support publishing updates. an update should be detected by the frontend whenever the blog post's last updated date is different than the published date. this should allow the post to be published again.

The publication information was relatively simple before:

public sealed record PublicationInformation
{
    public DateTimeOffset? PublishedDate { get; }

    public PublishStatus PublishStatus { get; }
}

Codex pointed out a flaw in my initial idea.

PublishedDate should not change every time the post is republished. It represents when the post was originally published, so it should remain immutable.

What we actually need is a second value that tracks when the currently published version was generated.

public PublicationInformation(
    DateTimeOffset? publishedDate,
    PublishStatus publishStatus,
    DateTimeOffset? lastPublishedDate = null)

The distinction is now pretty clear:

  • PublishedDate represents when the post was originally published.
  • LastPublishedDate represents when the current published version was last generated.

We also added a new response object that removes Cosmos-specific fields from the API contract and only returns what the consumer actually needs.

public sealed record BlogPostResponse(
    string Id,
    string UserId,
    string Title,
    string Description,
    PublicationInformationResponse PublicationInformation,
    int ReadingTime,
    IReadOnlyList<string> Tags,
    string Content,
    string Slug,
    DateTimeOffset ContentUpdatedDate,
    string DocumentType,
    SystemInformationResponse SystemInformation,
    string? Etag);

From there, the API calculates PublicationInformationResponse.HasUnpublishedChanges:

var hasUnpublishedChanges =
    publicationInformation is
    {
        PublishStatus: PublishStatus.Published,
        LastPublishedDate: not null
    } &&
    blogPost.ContentUpdatedDate > publicationInformation.LastPublishedDate;

The backend remains the authority on whether or not a post can be republished this way, keeping that business decision out of the frontend.

The UI does not need to understand how publication state works. It simply receives an explicit value indicating that the post contains unpublished changes.

That is the same general principle as the bucket example earlier: the consumer should not have to infer meaning when the backend already knows the answer.

Rendering Markdown

There is also an Astro Markdown renderer responsible for converting the blog post into the format expected by the static site:

public string Render(BlogPost blogPost)
{
    ArgumentNullException.ThrowIfNull(blogPost);

    var publishedDate = blogPost.PublicationInformation.PublishedDate
        ?? throw new InvalidOperationException(
            "A blog post must have a published date before it can be rendered.");

    using var markdown = new StringWriter(CultureInfo.InvariantCulture)
    {
        NewLine = "\n"
    };

    markdown.WriteLine("---");
    markdown.WriteLine(
        $"title: {JsonSerializer.Serialize(blogPost.Title, JsonOptions)}");
    markdown.WriteLine(
        $"description: {JsonSerializer.Serialize(blogPost.Description, JsonOptions)}");
    markdown.WriteLine($"pubDate: {publishedDate:yyyy-MM-dd}");
    markdown.WriteLine(
        $"readingTime: {JsonSerializer.Serialize($"{blogPost.ReadingTime} min read", JsonOptions)}");
    markdown.WriteLine("tags:");

    foreach (var tag in blogPost.Tags)
    {
        markdown.WriteLine(
            $"  - {JsonSerializer.Serialize(tag, JsonOptions)}");
    }

    markdown.WriteLine("---");
    markdown.WriteLine();
    markdown.Write(blogPost.Content);

    return markdown.ToString();
}

The renderer generates the Astro frontmatter, appends the Markdown content, and hands the resulting file off to the Azure DevOps publisher.

From there, the file is committed directly to the repository as described earlier.

Finishing the MVP

With that, the initial Blog Management API MVP is complete.

I started this project as an amalgamation of several things I have worked with at MarketOnce: microservice architecture, content management, API design, CI/CD with Azure DevOps, authentication with Entra, Cosmos DB, and deploying applications to Azure.

What started as a relatively small blog-management idea has turned into a compact end-to-end platform that lets me experiment with many of the same engineering decisions I deal with professionally, but in an environment where I can make all of the architectural decisions myself.

Going forward, I intend to use the project to practice Bicep templates for infrastructure automation and AKS management.

All of those experiences, including the decisions that work and the ones that do not, will be shared here on the BPE Blog.