api-design-reviewer

What This Skill Does

The API Design Reviewer by alirezarezvani is a robust engineering tool designed to enforce industry standards across your RESTful service architectures. It functions as an automated architectural assistant that evaluates API schemas, documentation, and implementation patterns. By integrating this skill, development teams can ensure that their endpoints adhere to consistent resource naming (kebab-case), proper HTTP verb usage, and standardized response formats. The skill goes beyond simple syntax checking; it provides a weighted scoring system that assesses documentation clarity, security postures, and overall developer experience. It acts as an automated 'design gatekeeper,' catching potential technical debt and integration friction before code ever hits production.

Installation

To integrate this skill into your OpenClaw environment, execute the following command in your terminal: clawhub install openclaw/skills/skills/alirezarezvani/api-design-reviewer

Use Cases

• Pre-Pull Request Review: Run the skill against a new API definition to catch breaking changes or non-conformity to existing organizational standards.
• Legacy Refactoring: Audit existing endpoints to identify areas where naming conventions or security headers are outdated.
• API Documentation Audits: Ensure that every parameter, status code, and error response is clearly documented and discoverable for third-party developers.
• Standardization: Enforce uniform design patterns across microservices teams to ensure that developers moving between services experience a consistent API interface.

Example Prompts

1. "Review my OpenAPI specification for the user-service and check for any breaking changes compared to the previous version."
2. "Analyze this endpoint design: /api/v1/GetOrderDetails?id=5. How can I make this more RESTful?"
3. "Evaluate the consistency of my current API response formats and provide a design score based on industry standards."

Tips & Limitations

• Tip: Always provide the full OpenAPI or Swagger definition to the tool for the most accurate scoring and breaking change detection.
• Tip: Treat the design scores as suggestions to foster discussion in your team's architecture reviews rather than immutable law.
• Limitation: The skill currently lacks the ability to execute live requests; it performs static analysis of your design documentation. Ensure your specification file is up-to-date with your current implementation. It does not perform deep security penetration testing, so pair this with dedicated security tools for sensitive production environments.