skills.rest
MudraMartin
MudraMartinCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Design and evolve public APIs with compatibility and versioning guidelines.

Updated Apr 23, 2026
Search Tags:#api design#semver#api versioning#public api#api compatibility
One-click install
npx skills add https://github.com/MudraMartin/dotlight-skillset --skill api-design-mudramartin
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/MudraMartin/dotlight-skillset/tree/main/dotnet/csharp-api-design
Command: npx skills add https://github.com/MudraMartin/dotlight-skillset --skill api-design-mudramartin

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill assists in the design and evolution of public APIs, ensuring compatibility and stability through versioning and change management.

Core Features & Use Cases

  • API Design Guidelines: Provides guidelines for API design, including compatibility types and extend-only design principles.
  • API Change Guidelines: Offers guidance on making safe and unsafe changes to APIs, along with a deprecation pattern.
  • API Approval Testing: Includes instructions for using automated API surface testing tools to prevent breaking changes.
  • Wire Compatibility: Discusses wire format changes and schema-based serialization for distributed systems.
  • Encapsulation Patterns: Offers best practices for internal APIs, sealing classes, and interface segregation.
  • Versioning Strategy: Explains semantic versioning and the Chesterton's Fence approach to API changes.
  • Pull Request Checklist: Provides a checklist for reviewing pull requests that touch public APIs.

Quick Start

Use the api-design skill to review and approve an API change in a pull request.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design public APIs with compatibility in mind?▼

To design public APIs with compatibility in mind, apply extend-only design principles and follow established API design guidelines. This ensures stability through structured versioning and change management.

What is the best way to handle API versioning and breaking changes?▼

The best way to handle API versioning and breaking changes is using semantic versioning alongside a structured deprecation pattern. This approach safely manages unsafe changes while maintaining wire compatibility.

How does wire compatibility work for schema-based serialization in distributed systems?▼

Wire compatibility for schema-based serialization ensures distributed systems tolerate wire format changes without breaking. It focuses on maintaining stable data contracts during API evolution.

How do I review an API change in a pull request?▼

Review an API change in a pull request by applying a dedicated API checklist. Use automated API surface testing tools to prevent breaking changes and verify compliance with deprecation patterns.

When should I use encapsulation patterns for internal APIs?▼

Use encapsulation patterns for internal APIs when sealing classes and applying interface segregation. This restricts unnecessary public exposure, ensuring internal API changes do not impact external consumers.

Related Skills

Explore More Software Engineering Skills→
wshaddixwshaddix
71

serialization

Compares .NET serialization formats for compatibility and performance.

Community
Advanced
robotijnrobotijn
3

api-contract-validator

Validate API implementations against OpenAPI, AsyncAPI, GraphQL, and Protobuf contracts.

Community
Advanced
yukieijiyukieiji

web-design-guidelines

Review web UI code against Web Interface Guidelines for accessibility and design compliance.

Community
Advanced
snoodleboot-iosnoodleboot-io
2

api-versioning-strategy-minimal

Implement semantic versioning and deprecation policies for API management.

Official
Intermediate