258 lines
9.6 KiB
Markdown
258 lines
9.6 KiB
Markdown
---
|
|
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
|