skills.rest
riandeoliveira
riandeoliveiraCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design

Guide extend-only evolution of public C# APIs to prevent breaking changes.

Updated Jan 29, 2024
Search Tags:#api compatibility#nuget versioning#wire compatibility#public api review#deprecation pattern#binary breaking changes
One-click install
npx skills add https://github.com/riandeoliveira/aspnet-template --skill api-design-riandeoliveira
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/riandeoliveira/aspnet-template/tree/main/.claude/skills/csharp-api-design
Command: npx skills add https://github.com/riandeoliveira/aspnet-template --skill api-design-riandeoliveira

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

The api-design skill helps you avoid breaking consumers when evolving public C# APIs and distributed wire formats by applying extend-only design and compatibility rules.

Core Features & Use Cases

  • Extend-only API evolution: Prevents breaking changes by only adding new capabilities (overloads, new types/members, and deprecation-first removals).
  • Compatibility guardrails: Covers API/source, binary, and wire compatibility so upgrades don’t fail at compile time, runtime, or during serialization.
  • Versioning and review strategy: Supports semantic versioning practices, safe deprecation patterns, and public API approval testing workflows to catch accidental surface changes.

Quick Start

Use the api-design skill to review a proposed public API change and identify which changes are safe, which are binary-breaking, and whether any wire/version strategy is required.

Frequently Asked Questions about api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent breaking changes when versioning a public C# API?▼

Prevent breaking changes in a public C# API by applying extend-only evolution, using additive patterns like new overloads and types, and ensuring immutable prior behavior so upgrades never fail at compile time or runtime.

What is the difference between source, binary, and wire compatibility in NuGet versioning?▼

Source compatibility means code compiles unchanged, binary compatibility ensures runtime binding succeeds without recompilation, and wire compatibility guarantees serialized data formats remain readable during distributed system protocol or persistence changes.

How do I safely deprecate and remove a public API member?▼

Safely remove a public API member by following a deprecation-before-removal workflow: mark the member as obsolete, allow consumers to migrate across versions, and then delete it in a subsequent major release.

Can I evolve a distributed wire format without breaking existing clients?▼

Evolve a distributed wire format without breaking clients by using opt-in wire evolution with a read-side first approach, ensuring older endpoints can still deserialize new messages while ignoring unknown fields.

How do I catch accidental public API surface changes during a pull request review?▼

Catch accidental public API surface changes during a pull request review by applying public API approval testing workflows that detect unauthorized modifications and identify which changes are safe or binary-breaking.

Does extend-only API design work for both NuGet libraries and distributed protocols?▼

Extend-only API design works for both NuGet libraries and distributed protocols by enforcing additive API patterns, deprecation-first removals, and compatibility guardrails across source, binary, and wire formats.

Related Skills

Explore More Software Engineering Skills→
rudironsonirudironsoni

dotnet-csharp-api-design

Guide public .NET API design with naming, parameter, and error conventions.

Community
Intermediate
bitpantrybitpantry

create-release

Automate NuGet package release planning and execution in GitHub repositories.

Community
Advanced
AGIBuildAGIBuild
10

dotnet-api-surface-validation

Track and enforce .NET library public API surfaces using Roslyn analyzers and Verify snapshots.

Community
Advanced
devingobledevingoble

api-design

Design stable public APIs using extend-only principles for NuGet packages.

Community
Advanced