/dotnet-techne-csharp-api-design

name: dotnet-techne-csharp-api-design
description: "Use when designing or changing public C#/.NET APIs with compatibility and versioning constraints. Keywords: breaking change, API design, backward compatibility, binary compatibility, deprecation strategy, versioning."
disable-model-invocation: false
user-invocable: true
metadata:
  author: Metalnib
  version: "1.0.0"
  trigger_keywords:
    - breaking change
    - api design
    - backward compatibility
    - binary compatibility
    - deprecation strategy
    - versioning

Public API Design and Compatibility

When to Use This Skill

Use this skill when:

• Designing public APIs for NuGet packages or libraries
• Making changes to existing public APIs
• Planning wire format changes for distributed systems
• Implementing versioning strategies
• Reviewing pull requests for breaking changes

---

The Three Types of Compatibility

| Type | Definition | Scope | |------|------------|-------| | **API/Source** | Code compiles against newer version | Public method signatures, types | | **Binary** | Compiled code runs against newer version | Assembly layout, method tokens | | **Wire** | Serialized data readable by other versions | Network protocols, persistence formats |

Breaking any of these creates upgrade friction for users.

---

Extend-Only Design

The foundation of stable APIs: **never remove or modify, only extend**.

Three Pillars

1. **Previous functionality is immutable** - Once released, behavior and signatures are locked 2. **New functionality through new constructs** - Add overloads, new types, opt-in features 3. **Removal only after deprecation period** - Years, not releases

Benefits

• Old code continues working in new versions
• New and old pathways coexist
• Upgrades are non-breaking by default
• Users upgrade on their schedule

**Resources:**

• [Extend-Only Design](https://aaronstannard.com/extend-only-design/)
• [OSS Compatibility Standards](https://aaronstannard.com/oss-compatibility-standards/)

---

API Change Guidelines

Safe Changes (Any Release)

// ADD new overloads with default parameters
public void Process(Order order, CancellationToken ct = default);

// ADD new optional parameters to existing methods
public void Send(Message msg, Priority priority = Priority.Normal);

// ADD new types, interfaces, enums
public interface IOrderValidator { }
public enum OrderStatus { Pending, Complete, Cancelled }

// ADD new members to existing types
public class Order
{
    public DateTimeOffset? ShippedAt { get; init; }  // NEW
}

Unsafe Changes (Never or Major Version Only)

// REMOVE or RENAME public members
public void ProcessOrder(Order order);  // Was: Process()

// CHANGE parameter types or order
public void Process(int orderId);  // Was: Process(Order order)

// CHANGE return types
public Order? GetOrder(string id);  // Was: public Order GetOrder()

// CHANGE access modifiers
internal class OrderProcessor { }  // Was: public

// ADD required parameters without defaults
public void Process(Order order, ILogger logger);  // Breaks callers!

Deprecation Pattern

// Step 1: Mark as obsolete with version (any release)
[Obsolete("Obsolete since v1.5.0. Use ProcessAsync instead.")]
public void Process(Order order) { }

// Step 2: Add new recommended API (same release)
public Task ProcessAsync(Order order, CancellationToken ct = default);

// Step 3: Remove in next major version (v2.0+)
// Only after users have had time to migrate

---

API Approval Testing

Prevent accidental breaking changes with automated API surface testing.

Using ApiApprover + Verify

dotnet add package PublicApiGenerator
dotnet add package Verify.Xunit

[Fact]
public Task ApprovePublicApi()
{
    var api = typeof(MyLibrary.PublicClass).Assembly.GeneratePublicApi();
    return Verify(api);
}

Creates `ApprovePublicApi.verified.txt`:

namespace MyLibrary
{
    public class OrderProcessor
    {
        public OrderProcessor() { }
        public void Process(Order order) { }
        public Task ProcessAsync(Order order, CancellationToken ct = default) { }
    }
}

**Any API change fails the test** - reviewer must explicitly approve changes.

PR Review Process

1. PR includes changes to `*.verified.txt` files 2. Reviewers see exact API surface changes in diff 3. Breaking changes are immediately visible 4. Conscious decision required to approve

---

Wire Compatibility

For distributed systems, serialized data must be readable across versions.

Requirements

| Direction | Requirement | |-----------|-------------| | **Backward** | Old writers → New readers (current version reads old data) | | **Forward** | New writers → Old readers (old version reads new data) |

Both are required for zero-downtime rolling upgrades.

Safely Evolving Wire Formats

**Phase 1: Add read-side support (opt-in)**

// New message type - readers deployed first
public sealed record HeartbeatV2(
    Address From,
    long SequenceNr,
    long CreationTimeMs);  // NEW field

// Deserializer handles both old and new
public object Deserialize(byte[] data, string manifest) => manifest switch
{
    "Heartbeat" => DeserializeHeartbeatV1(data),   // Old format
    "HeartbeatV2" => DeserializeHeartbeatV2(data), // New format
    _ => throw new NotSupportedException()
};

**Phase 2: Enable write-side (opt-out, next minor version)**

// Config to enable new format (off by default initially)
akka.cluster.use-heartbeat-v2 = on

**Phase 3: Make default (future version)**

After install base has absorbed read-side code.

Schema-Based Serialization

Prefer schema-based formats over reflection-based:

| Format | Type | Wire Compatibility | |--------|------|-------------------| | **Protocol Buffers** | Schema-based | Excellent - explicit field numbers | | **MessagePack** | Schema-based | Good - with contracts | | **System.Text.Json** |