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)

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