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

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

Naming Conventions for API Surface

Type Naming

Method Naming

Avoid Abbreviations in Public API

// WRONG -- abbreviations in public surface
public IReadOnlyList<TxnResult> GetRecentTxns(int cnt);

// CORRECT -- spelled out for clarity
public IReadOnlyList<TransactionResult> GetRecentTransactions(int count);

Parameter Ordering

Consistent parameter ordering reduces cognitive load.

Standard Order

1. Target/subject -- the primary entity being operated on
2. Required parameters -- essential inputs without defaults
3. Optional parameters -- inputs with sensible defaults
4. Cancellation token -- always last (convention enforced by CA1068)

public Task<Widget> GetWidgetAsync(
    int widgetId,                              // 1. Target
    WidgetOptions options,                     // 2. Required
    bool includeHistory = false,               // 3. Optional
    CancellationToken cancellationToken = default); // 4. Always last

Overload Progression

// Simple -- sensible defaults
public Task<Widget> GetWidgetAsync(int widgetId,
    CancellationToken cancellationToken = default)
    => GetWidgetAsync(widgetId, WidgetOptions.Default, cancellationToken);

// Detailed -- full control
public Task<Widget> GetWidgetAsync(int widgetId,
    WidgetOptions options,
    CancellationToken cancellationToken = default);

Return Type Selection

When to Return What

Prefer IReadOnlyList Over IEnumerable

// WRONG -- caller does not know if result is materialized or lazy
public IEnumerable<Widget> GetWidgets();

// CORRECT -- signals materialized, indexable collection
public IReadOnlyList<Widget> GetWidgets();

// CORRECT -- signals streaming/lazy evaluation explicitly
public IAsyncEnumerable<Widget> GetWidgetsStreamAsync(
    CancellationToken cancellationToken = default);

The Try Pattern

public bool TryGetWidget(int widgetId, [NotNullWhen(true)] out Widget? widget);

public Task<Widget?> TryGetWidgetAsync(int widgetId,
    CancellationToken cancellationToken = default);

Error Reporting Strategies

Exception Hierarchy

public class WidgetServiceException : Exception
{
    public WidgetServiceException(string message) : base(message) { }
    public WidgetServiceException(string message, Exception inner) : base(message, inner) { }
}

public class WidgetNotFoundException : WidgetServiceException
{
    public int WidgetId { get; }
    public WidgetNotFoundException(int widgetId)
        : base($"Widget {widgetId} not found.") => WidgetId = widgetId;
}

public class WidgetValidationException : WidgetServiceException
{
    public IReadOnlyList<string> Errors { get; }
    public WidgetValidationException(IReadOnlyList<string> errors)
        : base("Widget validation failed.") => Errors = errors;
}

When to Use Exceptions vs Return Values

Argument Validation

public Widget CreateWidget(string name, decimal price)
{
    ArgumentException.ThrowIfNullOrWhiteSpace(name);
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(price);

    return new Widget(name, price);
}

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
[Obsolete("Obsolete since v1.5.0. Use ProcessAsync instead.")]
public void Process(Order order) { }

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

// Step 3: Remove in next major version

Extension Points

Interface-Based Extension

// GOOD -- interface-based extension point
public interface IWidgetValidator
{
    ValueTask<bool> ValidateAsync(Widget widget, CancellationToken ct = default);
}

// GOOD -- delegate-based extension for simple hooks
public class WidgetServiceOptions
{
    public Func<Widget, CancellationToken, ValueTask>? OnWidgetCreated { get; set; }
}

Extension Method Guidelines

Wire Compatibility

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

Requirements

Both are required for zero-downtime rolling upgrades.

Safely Evolving Wire Formats

Phase 1: Add read-side support

public sealed record HeartbeatV2(
    Address From,
    long SequenceNr,
    long CreationTimeMs);  // NEW field

public object Deserialize(byte[] data, string manifest) => manifest switch
{
    "Heartbeat" => DeserializeHeartbeatV1(data),
    "HeartbeatV2" => DeserializeHeartbeatV2(data),
    _ => throw new NotSupportedException()
};

Phase 2: Enable write-side (next minor version)

akka.cluster.use-heartbeat-v2 = on

Defensive Serialization Design

public sealed class WidgetDto
{
    [JsonPropertyName("id")]
    public int Id { get; init; }

    [JsonPropertyName("name")]
    public required string Name { get; init; }

    [JsonPropertyName("category")]
    public string? Category { get; init; }

    [JsonPropertyName("priority")]
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
    public int Priority { get; init; }
}

Enum Serialization Strategy

// GOOD -- string serialization is rename-safe
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum WidgetStatus
{
    Draft,
    Active,
    Archived
}

// RISKY -- integer serialization breaks when members are reordered
public enum WidgetPriority
{
    Low = 0,
    Medium = 1,
    High = 2
}

API Approval Testing

Prevent accidental breaking changes with automated API surface testing.

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

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

Versioning Strategy

Semantic Versioning (Practical)

Key Principles

1. No surprise breaks - Even major versions should be announced
2. Extensions anytime - New APIs can ship in any release
3. Deprecate before remove - [Obsolete] for at least one minor version
4. Communicate timelines - Users need to plan upgrades

Pull Request Checklist

• No removed public members (use [Obsolete] instead)
• No changed signatures (add overloads instead)
• No new required parameters (use defaults)
• API approval test updated (.verified.txt changes reviewed)
• Wire format changes are opt-in (read-side first)
• Breaking changes documented (release notes, migration guide)

Anti-Patterns

Breaking Changes Disguised as Fixes

// "Bug fix" that breaks users
public async Task<Order> GetOrderAsync(OrderId id)  // Was sync!
{
}

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

Silent Behavior Changes

// Changing defaults breaks users
public void Configure(bool enableCaching = true)  // Was: false!

// Correct: New parameter with new name
public void Configure(
    bool enableCaching = false,
    bool enableNewCaching = true)

Polymorphic Serialization

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

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

Agent Gotchas

1. Do not use abbreviations in public API names -- spell out words.
2. Do not place CancellationToken before optional parameters -- CA1068 enforces last.
3. Do not return mutable collections from public APIs -- return IReadOnlyList<T>.
4. Do not change serialized property names without [JsonPropertyName] annotations.
5. Do not add required parameters to existing public methods -- add overload or use defaults.
6. Do not use async void in API surface -- return Task or ValueTask.
7. Do not design exception hierarchies without a base library exception.
8. Do not put extension methods in the System namespace.

Resources

• Making Public API Changes
• Wire Format Changes
• Extend-Only Design
• OSS Compatibility Standards
• Semantic Versioning
• PublicApiGenerator
• Framework Design Guidelines
• Breaking changes reference