api-design

1# Public API Design and Compatibility
2 
3## When to Use This Skill
4 
5Use this skill when:
6- Designing public APIs for NuGet packages or libraries
7- Making changes to existing public APIs
8- Planning wire format changes for distributed systems
9- Implementing versioning strategies
10- Reviewing pull requests for breaking changes
11 
12---
13 
14## The Three Types of Compatibility
15 
16| Type | Definition | Scope |
17|------|------------|-------|
18| **API/Source** | Code compiles against newer version | Public method signatures, types |
19| **Binary** | Compiled code runs against newer version | Assembly layout, method tokens |
20| **Wire** | Serialized data readable by other versions | Network protocols, persistence formats |
21 
22Breaking any of these creates upgrade friction for users.
23 
24---
25 
26## Extend-Only Design
27 
28The foundation of stable APIs: **never remove or modify, only extend**.
29 
30### Three Pillars
31 
321. **Previous functionality is immutable** - Once released, behavior and signatures are locked
332. **New functionality through new constructs** - Add overloads, new types, opt-in features
343. **Removal only after deprecation period** - Years, not releases
35 
36### Benefits
37 
38- Old code continues working in new versions
39- New and old pathways coexist
40- Upgrades are non-breaking by default
41- Users upgrade on their schedule
42 
43**Resources:**
44- [Extend-Only Design](https://aaronstannard.com/extend-only-design/)
45- [OSS Compatibility Standards](https://aaronstannard.com/oss-compatibility-standards/)
46 
47---
48…