A comprehensive API validation command for Claude Code that validates APIs against industry best practices using specialized AI agents.
- REST Best Practices - HTTP methods, resource naming, URL structure, status codes
- GraphQL Best Practices - Schema design, query complexity, N+1 detection
- OpenAPI/Swagger Validation - Spec completeness, documentation quality
- API Security - Authentication, authorization, input validation, rate limiting
- Performance Analysis - Caching, compression, query efficiency
- Consistency Checking - Naming patterns, response structure, error formats
- Versioning Analysis - Strategy validation, backward compatibility
- Claude Code CLI installed and configured
- An API project to validate
- Clone or download this repository
- Copy the folders to your project's
.claude/directory:
# From your project root
cp -r path/to/claude-code-api-validator/commands .claude/
cp -r path/to/claude-code-api-validator/api .claude/Your project structure should look like:
your-project/
├── .claude/
│ ├── commands/
│ │ └── api-validator.md
│ └── api/
│ ├── agents/
│ │ ├── rest-practices.md
│ │ ├── graphql-practices.md
│ │ ├── openapi-spec.md
│ │ ├── api-security.md
│ │ ├── api-performance.md
│ │ ├── api-consistency.md
│ │ └── api-versioning.md
│ └── templates/
│ └── api-validation-report.md
├── src/
└── ...
- (Optional) Add
api-reports/to your.gitignore:
echo "api-reports/" >> .gitignoreAfter installation, you can optimize the API validator for your specific codebase. This improves validation accuracy by focusing on your API framework's conventions and patterns.
Run this prompt in Claude Code:
I just installed the api-validator command in .claude/. Please:
1. Analyze my codebase to detect my API stack (framework, API style, authentication method, database)
2. Read the command files in .claude/commands/api-validator.md and .claude/api/agents/
3. Optimize each validation agent by:
- Removing checks for API styles I don't use (REST vs GraphQL)
- Adding validation rules specific to my framework (NestJS decorators, FastAPI patterns, etc.)
- Configuring security checks based on my auth implementation
- Adjusting performance checks based on my ORM/database
4. Keep the agent structure, validation categories, and output format unchanged
Show me what you'll change before applying.
In Claude Code, run the API validation command:
/api-validator
| Command | Description |
|---|---|
/api-validator |
Full validation (all checks) |
/api-validator rest |
REST API best practices only |
/api-validator graphql |
GraphQL best practices only |
/api-validator openapi |
OpenAPI/Swagger spec validation |
/api-validator security |
API security validation only |
/api-validator performance |
Performance analysis only |
/api-validator versioning |
Versioning strategy validation |
/api-validator consistency |
Consistency checking only |
| Check | Description |
|---|---|
| HTTP Methods | Correct usage of GET, POST, PUT, PATCH, DELETE |
| Resource Naming | Plural nouns, kebab-case, clear hierarchy |
| URL Structure | Proper nesting, query parameters |
| Status Codes | Appropriate response codes |
| Response Format | Consistent JSON structure |
| Pagination | Cursor/offset implementation |
| HATEOAS | Hypermedia links |
| Idempotency | Safe operation guarantees |
| Check | Description |
|---|---|
| Schema Design | Type structure, relationships |
| Query Complexity | Depth/complexity limits |
| N+1 Detection | DataLoader usage |
| Mutations | Input types, return values |
| Error Handling | Error types, extensions |
| Pagination | Relay-style connections |
| Subscriptions | Real-time patterns |
| Check | Description |
|---|---|
| Spec Completeness | Required fields, descriptions |
| Schema Definitions | Proper types, refs |
| Examples | Request/response examples |
| Security Schemes | Auth documentation |
| Error Responses | Error documentation |
| Versioning | API version info |
| Check | Description |
|---|---|
| Authentication | JWT, OAuth, API keys |
| Authorization | RBAC, scopes |
| Rate Limiting | Throttling configuration |
| Input Validation | Schema validation, sanitization |
| CORS | Cross-origin configuration |
| Error Exposure | Sensitive info leakage |
| Check | Description |
|---|---|
| Caching | ETags, Cache-Control |
| Compression | gzip, brotli |
| Payload Size | Response optimization |
| N+1 Queries | Database efficiency |
| Async Operations | Background processing |
| Connection Pooling | Resource management |
| Check | Description |
|---|---|
| Naming Conventions | camelCase/snake_case |
| Response Structure | Envelope patterns |
| Error Format | Standard error objects |
| Date Formats | ISO 8601 compliance |
| Null Handling | Consistent null/undefined |
| Check | Description |
|---|---|
| Version Strategy | URL, header, or query |
| Backward Compatibility | Breaking change detection |
| Deprecation | Sunset headers, notices |
| Migration Guides | Version transition docs |
The validator auto-detects and adapts to:
Node.js/TypeScript:
- Express.js
- NestJS
- Fastify
- Hapi
Python:
- FastAPI
- Django REST Framework
- Flask
PHP:
- Laravel
- Lumen
.NET:
- ASP.NET Core
- ASP.NET Web API
Go:
- Gin
- Echo
- Chi
Java:
- Spring Boot
- JAX-RS
- Quarkus
- Tech Stack Detection - Automatically detects your API framework and patterns
- Agent Execution - Spawns specialized agents for each validation domain
- Pattern Analysis - Analyzes code against best practice patterns
- Finding Collection - Aggregates and deduplicates findings
- Report Generation - Creates a markdown report in
api-reports/ - Fix Mode - Optionally offers to fix Critical/High issues
Reports are saved to api-reports/YYYY-MM-DD-HHmm-validation.md with:
- API Health Score (0-100)
- Executive Summary (severity counts)
- Endpoints Analyzed
- Critical Findings (full details + remediation)
- High Findings (full details + remediation)
- Medium Findings (abbreviated)
- Low Findings (list format)
- Best Practice Recommendations
| Level | Description | Action |
|---|---|---|
| Critical | Breaks API contract or security | Fix immediately |
| High | Significant deviation from standards | Fix this sprint |
| Medium | Best practice violation | Plan to fix |
| Low | Minor improvement opportunity | Fix when convenient |
| Info | Informational/suggestion | Consider |
To adapt for your specific needs:
- Tech stack detection - Modify Step 1 in
api-validator.md - Agent behavior - Edit individual agents in
api/agents/ - Report format - Modify
api/templates/api-validation-report.md - Severity thresholds - Adjust in agent files
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Submit a pull request
MIT License - see LICENSE file.
This tool performs static analysis and pattern matching. It provides guidance based on industry best practices but cannot guarantee detection of all issues. Always perform manual API reviews and testing for production systems.