api-design

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
• OSS Compatibility Standards

---

API Change Guidelines

Safe Changes (Any Release)

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