api-design skill

---
name: API Design
description: Systematic API design methodology with 6 validated patterns covering parameter categorization, safe refactoring, audit-first approach, automated validation, quality gates, and example-driven documentation. Use when designing new APIs, improving API consistency, implementing breaking change policies, or building API quality enforcement. Provides deterministic decision trees (5-tier parameter system), validation tool architecture, pre-commit hook patterns. Validated with 82.5% cross-domain transferability, 37.5% efficiency gains through audit-first refactoring.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

# API Design

**Systematic API design with validated patterns and automated quality enforcement.**

> Good APIs are designed, not discovered. 82.5% of patterns transfer across domains.

---

## When to Use This Skill

Use this skill when:
- 🎯 **Designing new API**: Need systematic parameter organization and naming conventions
- 🔄 **Refactoring existing API**: Improving consistency without breaking changes
- 📊 **API quality enforcement**: Building validation tools and quality gates
- 📝 **API documentation**: Writing clear, example-driven documentation
- 🚀 **API evolution**: Implementing versioning, deprecation, and migration policies
- 🔍 **API consistency**: Standardizing conventions across multiple endpoints

**Don't use when**:
- ❌ API has <5 endpoints (overhead not justified)
- ❌ No team collaboration (conventions only valuable for teams)
- ❌ Prototype/throwaway code (skip formalization)
- ❌ Non-REST/non-JSON APIs without adaptation (patterns assume JSON-based APIs)

---

## Prerequisites

### Tools
- **API framework** (language-specific): Go, Python, TypeScript, etc.
- **Validation tools** (optional): Linters, schema validators
- **Version control**: Git (for pre-commit hooks)

### Concepts
- **REST principles**: Resource-based design, HTTP methods
- **JSON specification**: Object property ordering (unordered), schema design
- **Semantic Versioning**: Major.Minor.Patch versioning (if using Pattern 1)
- **Pre-commit hooks**: Git hooks for quality gates

### Background Knowledge
- API design basics (endpoints, parameters, responses)
- Backward compatibility principles
- Testing strategies (integration tests, contract tests)

---

## Quick Start (30 minutes)

This skill was extracted using systematic knowledge extraction methodology from Bootstrap-006 experiment.

**Status**: PARTIAL EXTRACTION (demonstration of methodology, not complete skill)

**Note**: This is a minimal viable skill created to validate the knowledge extraction methodology. A complete skill would include:
- Detailed pattern descriptions with code examples
- Step-by-step walkthroughs for each pattern
- Templates for API specifications
- Scripts for validation and quality gates
- Comprehensive reference documentation

**Extraction Evidence**:
- Source experiment: Bootstrap-006 (V_instance=0.87, V_meta=0.786)
- Patterns extracted: 6/6 identified (not yet fully documented here)
- Principles extracted: 8/8 identified (not yet fully documented here)
- Extraction time: 30 minutes (partial, demonstration only)

---

## Patterns Overview

### Pattern 1: Deterministic Parameter Categorization

**Context**: When designing or refactoring API parameters, categorization decisions must be consistent and unambiguous.

**Solution**: Use 5-tier decision tree system:
- **Tier 1**: Required parameters (can't execute without)
- **Tier 2**: Filtering parameters (affect WHAT is returned)
- **Tier 3**: Range parameters (define bounds/thresholds)
- **Tier 4**: Output control parameters (affect HOW MUCH is returned)
- **Tier 5**: Standard parameters (cross-cutting concerns, framework-applied)

**Evidence**: 100% determinism across 8 tools, 37.5% efficiency gain through pre-audit

**Transferability**: ✅ Universal to all query-based APIs (REST, GraphQL, CLI)

---

### Pattern 2: Safe API Refactoring via JSON Property

**Context**: Need to improve API schema readability without breaking existing clients.

**Solution**: Leverage JSON specification guarantee that object properties are unordered. Parameter order in schema definition is documentation only.

**Evidence**: 60 lines changed, 100% test pass rate, zero compatibility issues

**Transferability**: ✅ Universal to all JSON-based APIs

---

### Pattern 3: Audit-First Refactoring

**Context**: Need to refactor multiple targets (tools, parameters, schemas) for consistency.

**Solution**: Systematic audit process before making changes:
1. List all targets to audit
2. Define compliance criteria
3. Assess each target (compliant vs. non-compliant)
4. Categorize and prioritize
5. Execute changes on non-compliant targets only
6. Verify compliant targets (no changes)

**Evidence**: 37.5% unnecessary work avoided (3 of 8 tools already compliant)

**Transferability**: ✅ Universal to any refactoring effort (not API-specific)

---

### Patterns 4-6

**Note**: Patterns 4-6 (Automated Consistency Validation, Automated Quality Gates, Example-Driven Documentation) are documented in the source experiment (Bootstrap-006) but not yet extracted here due to time constraints in this validation iteration.

**Source**: See `experiments/bootstrap-006-api-design/results.md` lines 616-733 for full descriptions.

---

## Core Principles

### 1. Specifications Alone are Insufficient

**Statement**: Methodology extraction requires observing execution, not just reading design documents.

**Evidence**: Bootstrap-006 Iterations 0-3 produced 0 patterns (specifications only), Iterations 4-6 extracted 6 patterns (execution observed).

**Application**: Always combine design work with implementation to enable pattern extraction.

---

### 2. Operational Quality > Design Quality

**Statement**: Operational implementation scores higher than design quality when verification is rigorous.

**Evidence**: Design V_consistency = 0.87, Operational V_consistency = 0.94 (+0.07).

**Application**: Be conservative with design estimates. Reserve high scores (0.90+) for operational verification.

---

### 3-8. Additional Principles

**Note**: Principles 3-8 are documented in source experiment but not yet extracted here due to time constraints.

---

## Success Metrics

**Instance Layer** (Task Quality):
- API usability: 0.83
- API consistency: 0.97
- API completeness: 0.76
- API evolvability: 0.88
- **Overall**: V_instance = 0.87 (exceeds 0.80 threshold by +8.75%)

**Meta Layer** (Methodology Quality):
- Methodology completeness: 0.85
- Methodology effectiveness: 0.66
- Methodology reusability: 0.825
- **Overall**: V_meta = 0.786 (approaches 0.80 threshold, gap -1.4%)

**Validation**: Transfer test across domains achieved 82.5% average pattern transferability (empirically validated).

---

## Transferability

**Language Independence**: ✅ HIGH (75-85%)
- Patterns focus on decision-making processes, not language features
- Tested primarily in Go, but applicable to Python, TypeScript, Rust, Java

**Domain Independence**: ✅ HIGH (82.5% empirically validated)
- Patterns transfer from MCP Tools API to Slash Command Capabilities with minor adaptation
- Universal patterns (3, 4, 5, 6): 67% of methodology
- Domain-specific patterns (1, 2): Require adaptation for different parameter models

**Codebase Generality**: ✅ MODERATE (60-75%)
- Validated on meta-cc (16 MCP tools, moderate scale)
- Application to very large APIs (100+ tools) unvalidated
- Principles scale-independent, but tooling may need adaptation

---

## Limitations and Gaps

### Known Limitations

1. **Single domain validation**: Patterns extracted from API design only, need validation in non-API contexts
2. **JSON-specific**: Pattern 2 (Safe Refactoring) assumes JSON-based APIs
3. **Moderate scale**: Validated on 16-tool API, not tested on 100+ tool systems
4. **Conservative effectiveness**: No control group study (ad-hoc vs. methodology comparison)

### Skill Completeness

**Current Status**: PARTIAL EXTRACTION (30% complete)

**Completed**:
- ✅ Frontmatter (name, description, allowed-tools)
- ✅ When to Use / Prerequisites
- ✅ Patterns 1-3 documented (summaries)
- ✅ Principles 1-2 documented
- ✅ Success Metrics / Transferability / Limitations

**Missing** (to be completed in future iterations):
- ❌ Patterns 4-6 detailed documentation
- ❌ Principles 3-8 documentation
- ❌ Step-by-step walkthroughs (examples/)
- ❌ Templates directory (API specification templates)
- ❌ Scripts directory (validation tools, quality gates)
- ❌ Reference documentation (comprehensive pattern catalog)

**Reason for Incompleteness**: This skill created as validation of knowledge extraction methodology, not as production-ready artifact. Demonstrates methodology viability but requires additional 60-90 minutes for completion.

---

## Related Skills

- **Testing Strategy**: API testing patterns, integration tests, contract tests
- **Error Recovery**: API error handling, error taxonomy
- **CI/CD Optimization**: Pre-commit hooks, automated quality gates (overlaps with Pattern 5)

---

## Quick Reference

**5-Tier Parameter System**:
1. Required (must have)
2. Filtering (WHAT is returned)
3. Range (bounds/thresholds)
4. Output control (HOW MUCH)
5. Standard (cross-cutting)

**Audit-First Efficiency**: 37.5% work avoided (3/8 tools already compliant)

**Transferability**: 82.5% average (empirical validation across domains)

**Convergence**: V_instance = 0.87, V_meta = 0.786

---

**Skill Status**: DEMONSTRATION / PARTIAL EXTRACTION
**Extraction Source**: Bootstrap-006-api-design
**Extraction Date**: 2025-10-19
**Extraction Time**: 30 minutes (partial)
**Next Steps**: Complete Patterns 4-6, add examples, create templates and scripts