api-design

Aaronontheweb/dotnet-skillsCoding AgentsAudit passedSnapshot bccc78bb0b52

Installs: 0

Summary

Design stable, compatible public APIs using extend-only design principles. Manage API compatibility, wire compatibility, and versioning for NuGet packages and distributed systems.

SKILL.md

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

Previous functionality is immutable - Once released, behavior and signatures are locked
New functionality through new constructs - Add overloads, new types, opt-in features
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:

// SAFE: Add NEW overload methods that delegate to existing methods
// Existing method - do not modify its signature
public void Process(Order order) { ... }
// New overload - safe to add
public void Process(Order order, CancellationToken ct)
{
    // implementation that handles cancellation
}

// SAFE: Add NEW overloads for additional functionality
// Existing method - do not modify
public void Send(Message msg) { ... }
// New overload - safe to add
public void Send(Message msg, Priority priority)
{
    // implementation that handles priority
}

// 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
}

// 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 optional parameters to EXISTING methods (binary incompatible!)
// The compiled IL method signature changes - callers compiled against
// the old signature will get MissingMethodException at runtime.
// Optional parameter defaults are baked into the CALLER's assembly at compile time.
public void Process(Order order, CancellationToken ct = default);  // Breaks binary compat!
public void Send(Message msg, Priority priority = Priority.Normal);  // Breaks binary compat!
// Correct approach: add a NEW overload method instead (see Safe Changes above)

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

// 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

dotnet add package PublicApiGenerator
dotnet add package Verify.Xunit

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

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

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

// 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()
};

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

Format	Type	Wire Compatibility
Protocol Buffers	Schema-based	Excellent - explicit field numbers
MessagePack	Schema-based	Good - with contracts
System.Text.Json	Schema-based (with source gen)	Good - explicit properties
Newtonsoft.Json	Reflection-based	Poor - type names in payload
BinaryFormatter	Reflection-based	Terrible - never use

// Attribute for documentation
[InternalApi]
public class ActorSystemImpl { }

// Namespace convention
namespace MyLibrary.Internal
{
    public class InternalHelper { }  // Public for extensibility, not for users
}

// DO: Seal classes not designed for inheritance
public sealed class OrderProcessor { }

// DON'T: Leave unsealed by accident
public class OrderProcessor { }  // Users might inherit, blocking changes

// DO: Small, focused interfaces
public interface IOrderReader
{
    Order? GetById(OrderId id);
}

public interface IOrderWriter
{
    Task SaveAsync(Order order);
}

// DON'T: Monolithic interfaces (can't add methods without breaking)
public interface IOrderRepository
{
    Order? GetById(OrderId id);
    Task SaveAsync(Order order);
    // Adding new methods breaks all implementations!
}

Version	Changes Allowed
Patch (1.0.x)	Bug fixes, security patches
Minor (1.x.0)	New features, deprecations, obsolete removal
Major (x.0.0)	Breaking changes, old API removal

// "Bug fix" that breaks users
public async Task<Order> GetOrderAsync(OrderId id)  // Was sync!
{
    // "Fixed" to be async - but breaks all callers
}

// Correct: Add new method, deprecate old
[Obsolete("Use GetOrderAsync instead")]
public Order GetOrder(OrderId id) => GetOrderAsync(id).Result;

public async Task<Order> GetOrderAsync(OrderId id) { }

// Changing defaults breaks users who relied on old behavior
public void Configure(bool enableCaching = true)  // Was: false!

// Correct: New parameter with new name
public void Configure(
    bool enableCaching = false,  // Original default preserved
    bool enableNewCaching = true)  // New behavior opt-in

// AVOID: Type names in wire format
{ "$type": "MyApp.Order, MyApp", "Id": 123 }

// Renaming Order class = wire break!

// PREFER: Explicit discriminators
{ "type": "order", "id": 123 }

api-design

Summary

SKILL.md

Public API Design and Compatibility

When to Use This Skill

The Three Types of Compatibility

Extend-Only Design

Three Pillars

Benefits

API Change Guidelines

Safe Changes (Any Release)

Unsafe Changes (Never or Major Version Only)

Deprecation Pattern

API Approval Testing

Using ApiApprover + Verify

PR Review Process

Wire Compatibility

Requirements

Safely Evolving Wire Formats

Schema-Based Serialization

Encapsulation Patterns

Internal APIs

Sealing Classes

Interface Segregation

Versioning Strategy

Semantic Versioning (Practical)

Key Principles

Chesterton's Fence

Pull Request Checklist

Anti-Patterns

Breaking Changes Disguised as Fixes

Silent Behavior Changes

Polymorphic Serialization

Resources

Related skills