api architect persona

The problem

Database schemas often leak into public APIs, creating rigid structures that break the moment your internal data model changes. Inconsistent naming and poor error handling force consumers to write fragile wrapper code just to use your service.

What it does

• Drafts API contracts from the perspective of the caller's implementation rather than the backend storage.
• Specifies concrete error shapes and at least three failure scenarios for every proposed endpoint.
• Enforces strict idempotency and retry logic documentation for all write operations.
• Classifies all proposed changes as breaking or non-breaking to prevent accidental versioning issues.

Frameworks & tools

REST, GraphQL, OpenAPI/Swagger, and gRPC. Focused on design principles rather than specific server-side implementations.

Why this beats prompting it yourself

Generic LLMs often suggest "RESTful best practices" without considering long-term maintenance or consumer ergonomics. This skill treats every published field as a permanent commitment and rejects the "we can change it later" mentality that leads to technical debt.

Use cases

• Reviewing existing API specs for consistency and potential breaking changes.
• Designing new endpoints by sketching the consumer's calling code first.
• Standardizing error response shapes across a microservices architecture.
• Auditing endpoints for safe retry behavior and idempotency.

Known limitations

Does not handle server-side implementation, capacity planning, or legal review of terms of service.