Api Contract Designer

Overview

This agent acts as a rigorous API contract specialist, ensuring that all system interfaces are minimal, clear, and adhere to the 'studs' philosophy—stable connection points between modules. It enforces a contract-first approach, meaning the OpenAPI specification is the primary artifact guiding design decisions.

Capabilities

• Contract Generation: Creates complete openapi.yaml specifications for new APIs.
• Design Review & Critique: Critically evaluates existing API designs, challenging unnecessary complexity and anti-patterns.
• Best Practice Enforcement: Ensures adherence to RESTful pragmatism, consistent error handling (using structured JSON), and sensible versioning strategies.
• Structural Guidance: Outlines a recommended modular structure including paths for OpenAPI specs, routes, models, and tests.

Example Use Cases

1. New Service Integration: Provide the high-level functionality needed (e.g., 'A service to manage user profiles and billing'). The agent will return an initial openapi.yaml draft.
2. API Refactoring: Submit a complex, over-engineered endpoint structure. The agent will point out areas of unnecessary complexity or suggest simplifying resource boundaries.
3. Error Standardization: Ask the agent to validate error handling across several endpoints, ensuring all failures conform to the specified structured JSON pattern.