- Home
- Skills
- APIs & Backend
- api architect
Works with the AI Agents you already use
api architect
Design, review, and evolve REST, GraphQL, and gRPC API contracts with contract-first discipline and security audits.
$5.99
api architect
Example session with this skill installed
Review the proposed changes in openapi.yaml for any breaking changes and ensure the new /orders/{id}/refund endpoint follows our existing error response conventions.
Inspect the existing API specification and implementation where available.
Identify
- Breaking changes affecting existing API consumers.
- Inconsistencies with existing response and error conventions.
- Missing HTTP status codes and response schemas.
- Potential security and authorization concerns.
- Documentation inconsistencies.
Provide a detailed review with evidence from the project files, a proposed corrected API contract, and a migration recommendation where necessary.
Do not invent existing endpoints, consumers, or implementation details. Clearly distinguish verified findings from assumptions.
Do not modify any files until you have presented your findings and recommendations.
- Read your context and instructions
- Compiled the api architect
I have analyzed the diff for openapi.yaml and compared the new /orders/{id}/refund endpoint against your existing patterns in src/middleware/error-handler.ts.
API Review Report
| Feature | Finding | Status |
|---|---|---|
| Breaking Changes | Removed tax_identifier from User schema without a major version bump. | High Risk |
| Error Consistency | The refund endpoint uses message field, but project standard is error_code and developer_info. | Recommendation |
| Security | Missing 403 Forbidden response definition for unauthorized refund attempts. | Verified |
| Naming | Endpoint uses kebab-case which matches the existing /user-profiles convention. | Verified |
Proposed Schema Fix
/orders/{id}/refund:
post:
summary: Refund an order
responses:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
Compatibility Verdict
FAILED: The removal of tax_identifier will break the Android mobile client and the Python SDK. I recommend marking this field as deprecated: true instead of removing it.
Next steps
- Revert the deletion of
tax_identifierand add a deprecation warning. - Update the refund endpoint error response to use the
ErrorResponsecomponent. - Run
spectral lint openapi.yamlto confirm structural validity.
Connects securely to your tools. The creator never sees your data.
About this skill
Stop shipping APIs with breaking changes or inconsistent schemas. This skill handles the rigorous work of designing, reviewing, and documenting API contracts with a focus on stability and security. It prevents spec-to-code drift by inspecting your actual implementation before proposing any changes.
What it does
- Contract-first design: Author and evolve OpenAPI, GraphQL SDL, AsyncAPI, and gRPC Protobuf definitions.
- Security audits: Scans contracts for OWASP API Top 10 vulnerabilities like BOLA and mass assignment.
- Breaking change detection: Analyzes proposed schema changes for backward compatibility risks.
- Consistency enforcement: Aligns naming, error models, pagination, and versioning with existing project conventions.
- Documentation generation: Produces technical docs, changelogs, and usage examples derived from verified code.
How it works
- Understand: The skill inspects your routes, schemas, and existing specs to identify the API style and conventions.
- Analyze: It flags inconsistencies, security gaps, and drift between your documentation and implementation.
- Design/Plan: It proposes a contract diff and migration steps, explaining the rationale behind architectural choices.
- Validate: It runs available linters (Spectral, buf) and validators to confirm structural and behavioral correctness.
Frameworks & tools
Works with REST, GraphQL, gRPC, and event-driven architectures. Supports OpenAPI/Swagger, AsyncAPI, Protobuf, and GraphQL SDL. Compatible with linters like Spectral and buf.
Why this beats prompting it yourself
Generic prompts often invent endpoints or ignore existing project conventions. This skill enforces an evidence-based workflow that distinguishes between verified facts, assumptions, and recommendations, ensuring your API remains stable for consumers.
Use cases
- Add a new resource to a REST API while maintaining existing pagination and error patterns.
- Review a GraphQL schema for N+1 risks or inconsistent type naming.
- Draft a migration plan for deprecating a v1 endpoint in favor of v2.
- Generate an OpenAPI spec for an existing codebase that lacks documentation.
Known limitations
Does not handle internal business logic, database migrations, or auth implementation. Restricted to the API contract layer.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for APIs & Backend.
No implementation of business logic or auth internals. Cannot perform behavioral validation without existing project test suites. Limited to contract-layer changes.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 13 days ago