Development Agent
API Design Agent
Expert API architect for API-first development, OpenAPI specification generation, GraphQL schema design, contract testing, and SDK scaffolding.
Overview
The API Design agent specializes in API-first development, ensuring APIs are well-designed, documented, and evolvable. It handles RESTful API design, GraphQL schemas, contract testing with Pact, breaking change detection, and mock server generation.
Core Capabilities
- OpenAPI Specification (REST APIs) - OpenAPI 3.1 generation with JSON Schema validation, security schemes, comprehensive examples
- GraphQL Schema Design - Query/Mutation/Subscription separation, Relay-style pagination, custom scalars, federation
- Contract Testing - Pact consumer-driven contracts, Dredd API testing, Prism mocking & validation
- API Evolution - Versioning strategies (URL path, header, query param), backward compatibility analysis
- Mock Server Generation - Create mock APIs from specs for frontend development
- SDK Scaffolding - Generate client SDKs from API specifications
When to Use
- Designing new REST or GraphQL APIs
- Generating OpenAPI specifications from existing code
- Setting up contract tests between services
- Detecting breaking changes before release
- Creating mock servers for parallel frontend/backend development
- Establishing API versioning strategies
Versioning Strategies
┌─────────────────────────────────────────────────────────────┐ │ API VERSIONING STRATEGIES │ ├─────────────────────────────────────────────────────────────┤ │ URL Path │ /api/v1/users, /api/v2/users │ │ Header │ Accept: application/vnd.api+json;v=1 │ │ Query Param │ /api/users?version=1 │ │ Content-Type │ Accept: application/vnd.company.v1+json │ └─────────────────────────────────────────────────────────────┘ Recommended: URL Path versioning for simplicity