skills.rest
devingoble
devingobleCOMMUNITY
Explore all skills by this author →
GitHub

api-design

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

Updated Dec 4, 2022
Search Tags:#csharp#versioning#api design#compatibility#distributed systems#nuget#extend-only
One-click install
npx skills add https://github.com/devingoble/CloudOStat --skill api-design-devingoble
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/devingoble/CloudOStat/tree/main/.github/skills/csharp-api-design
Command: npx skills add https://github.com/devingoble/CloudOStat --skill api-design-devingoble

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill addresses the critical challenge of designing and maintaining public APIs that remain stable, compatible, and easy for consumers to use over time, preventing breaking changes and reducing upgrade friction.

Core Features & Use Cases

  • Extend-Only Design: Enforces principles to only add to APIs, never remove or break existing functionality.
  • Compatibility Management: Covers API (source), binary, and wire compatibility for NuGet packages and distributed systems.
  • Versioning Strategies: Provides guidance on semantic versioning and deprecation patterns.
  • API Approval Testing: Integrates tools like ApiApprover and Verify to catch breaking changes automatically.
  • Wire Format Evolution: Details safe patterns for evolving data formats in distributed systems.
  • Use Case: When developing a new version of a widely used .NET library, this skill ensures that existing applications using the previous version will continue to function without modification, while new features are introduced seamlessly.

Quick Start

Use the api-design skill to review a proposed change to the public API of the OrderProcessor class to ensure it follows extend-only principles.

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 in public C# API design?▼

To prevent breaking changes in C# API design, apply extend-only principles by only adding new functionality rather than removing or modifying existing members. This approach ensures source and binary compatibility for consumers using older package versions.

What is the difference between API, binary, and wire compatibility in distributed systems?▼

API compatibility ensures source code compiles, binary compatibility allows drop-in DLL replacement without recompilation, and wire compatibility guarantees serialized data formats remain readable across different versions in distributed systems.

How do I use API approval testing to catch breaking changes in NuGet packages?▼

API approval testing catches breaking changes in NuGet packages by integrating tools like ApiApprover and Verify. These tools automatically compare public API surfaces against a baseline, failing tests if unauthorized modifications are detected.

What are safe patterns for wire format evolution in distributed systems?▼

Safe wire format evolution in distributed systems uses extend-only patterns to add new fields or messages while ignoring unknown data. This ensures forward and backward compatibility between services communicating over different versions.

Can I use semantic versioning and deprecation strategies for .NET library versioning?▼

Yes, you can use semantic versioning and deprecation strategies for .NET library versioning. This involves marking obsolete APIs with deprecation attributes and incrementing version numbers to signal the impact of changes to consumers.

Does extend-only API design work for updating widely used .NET libraries?▼

Extend-only API design works effectively for updating widely used .NET libraries by ensuring existing applications continue functioning without modification. New features are added seamlessly without breaking previous consumer implementations.

Related Skills

Explore More Software Engineering Skills→
akokenakoken
3

csharp-api-design

Guide extend-only public API design for C# libraries and NuGet packages.

Community
Advanced
AGIBuildAGIBuild
10

api-design

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

Community
Advanced
BuggzBuggz

api-design

Guide extend-only API design for NuGet packages and distributed systems.

Community
Advanced
constellizeconstellize
1

write-contract-tests

Generate strict contract tests from constellation-map.md and code-generation-plan files.

Official
Advanced