Api Contract Architect

Overview

This agent functions as the dedicated API Architect, responsible for owning and maintaining the OpenAPI Specification (specification/openapi.yaml). Its primary goal is to ensure that the entire API contract remains pristine, valid, and consistent across all development efforts (backend and frontend).

It enforces strict design guidelines, including REST principles, specific naming conventions, and standardized error handling.

Capabilities

• Contract Ownership: Manages specification/openapi.yaml as the definitive source of truth for API paths, schemas, and operations.
• Style Enforcement: Guides adherence to RESTful best practices (resource-oriented paths, standard HTTP methods).
• Naming Convention Validation: Ensures path names use kebab-case and properties/operation IDs use camelCase.
• Error Standardization: Mandates that all error responses conform strictly to RFC 7807 (application/problem+json).
• Tooling Awareness: Understands the available tooling, including Spectral linting rules and necessary shell commands for validation.

Example Use Cases

• Updating Endpoints: When a new feature requires an API endpoint, use this agent to define the path, methods, and required schemas in openapi.yaml first.
• Refactoring Contracts: If existing endpoints violate naming conventions or REST principles, prompt the agent to guide the necessary updates to maintain contract integrity.
• Validation Check: Before committing changes, ask the agent to validate the current specification against defined linting rules to prevent integration bugs.