# Send API Design Reviewer to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "api-design-reviewer", "name": "API Design Reviewer", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/alirezarezvani/api-design-reviewer", "canonicalUrl": "https://clawhub.ai/alirezarezvani/api-design-reviewer", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/api-design-reviewer", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-design-reviewer", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "SKILL.md", "references/api_antipatterns.md", "references/rest_design_rules.md", "scripts/api_linter.py", "scripts/api_scorecard.py", "scripts/breaking_change_detector.py" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "api-design-reviewer", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-29T06:02:17.604Z", "expiresAt": "2026-05-06T06:02:17.604Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-design-reviewer", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-design-reviewer", "contentDisposition": "attachment; filename=\"api-design-reviewer-2.1.1.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "api-design-reviewer" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/api-design-reviewer" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/api-design-reviewer", "downloadUrl": "https://openagent3.xyz/downloads/api-design-reviewer", "agentUrl": "https://openagent3.xyz/skills/api-design-reviewer/agent", "manifestUrl": "https://openagent3.xyz/skills/api-design-reviewer/agent.json", "briefUrl": "https://openagent3.xyz/skills/api-design-reviewer/agent.md" } } ``` ## Documentation ### API Design Reviewer Tier: POWERFUL Category: Engineering / Architecture Maintainer: Claude Skills Team ### Overview The API Design Reviewer skill provides comprehensive analysis and review of API designs, focusing on REST conventions, best practices, and industry standards. This skill helps engineering teams build consistent, maintainable, and well-designed APIs through automated linting, breaking change detection, and design scorecards. ### 1. API Linting and Convention Analysis Resource Naming Conventions: Enforces kebab-case for resources, camelCase for fields HTTP Method Usage: Validates proper use of GET, POST, PUT, PATCH, DELETE URL Structure: Analyzes endpoint patterns for consistency and RESTful design Status Code Compliance: Ensures appropriate HTTP status codes are used Error Response Formats: Validates consistent error response structures Documentation Coverage: Checks for missing descriptions and documentation gaps ### 2. Breaking Change Detection Endpoint Removal: Detects removed or deprecated endpoints Response Shape Changes: Identifies modifications to response structures Field Removal: Tracks removed or renamed fields in API responses Type Changes: Catches field type modifications that could break clients Required Field Additions: Flags new required fields that could break existing integrations Status Code Changes: Detects changes to expected status codes ### 3. API Design Scoring and Assessment Consistency Analysis (30%): Evaluates naming conventions, response patterns, and structural consistency Documentation Quality (20%): Assesses completeness and clarity of API documentation Security Implementation (20%): Reviews authentication, authorization, and security headers Usability Design (15%): Analyzes ease of use, discoverability, and developer experience Performance Patterns (15%): Evaluates caching, pagination, and efficiency patterns ### Resource Naming Conventions ✅ Good Examples: - /api/v1/users - /api/v1/user-profiles - /api/v1/orders/123/line-items ❌ Bad Examples: - /api/v1/getUsers - /api/v1/user_profiles - /api/v1/orders/123/lineItems ### HTTP Method Usage GET: Retrieve resources (safe, idempotent) POST: Create new resources (not idempotent) PUT: Replace entire resources (idempotent) PATCH: Partial resource updates (not necessarily idempotent) DELETE: Remove resources (idempotent) ### URL Structure Best Practices Collection Resources: /api/v1/users Individual Resources: /api/v1/users/123 Nested Resources: /api/v1/users/123/orders Actions: /api/v1/users/123/activate (POST) Filtering: /api/v1/users?status=active&role=admin ### 1. URL Versioning (Recommended) /api/v1/users /api/v2/users Pros: Clear, explicit, easy to route Cons: URL proliferation, caching complexity ### 2. Header Versioning GET /api/users Accept: application/vnd.api+json;version=1 Pros: Clean URLs, content negotiation Cons: Less visible, harder to test manually ### 3. Media Type Versioning GET /api/users Accept: application/vnd.myapi.v1+json Pros: RESTful, supports multiple representations Cons: Complex, harder to implement ### 4. Query Parameter Versioning /api/users?version=1 Pros: Simple to implement Cons: Not RESTful, can be ignored ### Offset-Based Pagination { "data": [...], "pagination": { "offset": 20, "limit": 10, "total": 150, "hasMore": true } } ### Cursor-Based Pagination { "data": [...], "pagination": { "nextCursor": "eyJpZCI6MTIzfQ==", "hasMore": true } } ### Page-Based Pagination { "data": [...], "pagination": { "page": 3, "pageSize": 10, "totalPages": 15, "totalItems": 150 } } ### Standard Error Structure { "error": { "code": "VALIDATION_ERROR", "message": "The request contains invalid parameters", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "Email address is not valid" } ], "requestId": "req-123456", "timestamp": "2024-02-16T13:00:00Z" } } ### HTTP Status Code Usage 400 Bad Request: Invalid request syntax or parameters 401 Unauthorized: Authentication required 403 Forbidden: Access denied (authenticated but not authorized) 404 Not Found: Resource not found 409 Conflict: Resource conflict (duplicate, version mismatch) 422 Unprocessable Entity: Valid syntax but semantic errors 429 Too Many Requests: Rate limit exceeded 500 Internal Server Error: Unexpected server error ### Bearer Token Authentication Authorization: Bearer ### API Key Authentication X-API-Key: Authorization: Api-Key ### OAuth 2.0 Flow Authorization: Bearer ### Role-Based Access Control (RBAC) { "user": { "id": "123", "roles": ["admin", "editor"], "permissions": ["read:users", "write:orders"] } } ### Headers X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1640995200 ### Response on Limit Exceeded { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests", "retryAfter": 3600 } } ### Example Implementation { "id": "123", "name": "John Doe", "email": "john@example.com", "_links": { "self": { "href": "/api/v1/users/123" }, "orders": { "href": "/api/v1/users/123/orders" }, "profile": { "href": "/api/v1/users/123/profile" }, "deactivate": { "href": "/api/v1/users/123/deactivate", "method": "POST" } } } ### Idempotent Methods GET: Always safe and idempotent PUT: Should be idempotent (replace entire resource) DELETE: Should be idempotent (same result) PATCH: May or may not be idempotent ### Idempotency Keys POST /api/v1/payments Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000 ### Safe Changes (Non-Breaking) Adding optional fields to requests Adding fields to responses Adding new endpoints Making required fields optional Adding new enum values (with graceful handling) ### Breaking Changes (Require Version Bump) Removing fields from responses Making optional fields required Changing field types Removing endpoints Changing URL structures Modifying error response formats ### Required Components API Information: Title, description, version Server Information: Base URLs and descriptions Path Definitions: All endpoints with methods Parameter Definitions: Query, path, header parameters Request/Response Schemas: Complete data models Security Definitions: Authentication schemes Error Responses: Standard error formats ### Best Practices Use consistent naming conventions Provide detailed descriptions for all components Include examples for complex objects Define reusable components and schemas Validate against OpenAPI specification ### Caching Strategies Cache-Control: public, max-age=3600 ETag: "123456789" Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT ### Efficient Data Transfer Use appropriate HTTP methods Implement field selection (?fields=id,name,email) Support compression (gzip) Implement efficient pagination Use ETags for conditional requests ### Resource Optimization Avoid N+1 queries Implement batch operations Use async processing for heavy operations Support partial updates (PATCH) ### Input Validation Validate all input parameters Sanitize user data Use parameterized queries Implement request size limits ### Authentication Security Use HTTPS everywhere Implement secure token storage Support token expiration and refresh Use strong authentication mechanisms ### Authorization Controls Implement principle of least privilege Use resource-based permissions Support fine-grained access control Audit access patterns ### api_linter.py Analyzes API specifications for compliance with REST conventions and best practices. Features: OpenAPI/Swagger spec validation Naming convention checks HTTP method usage validation Error format consistency Documentation completeness analysis ### breaking_change_detector.py Compares API specification versions to identify breaking changes. Features: Endpoint comparison Schema change detection Field removal/modification tracking Migration guide generation Impact severity assessment ### api_scorecard.py Provides comprehensive scoring of API design quality. Features: Multi-dimensional scoring Detailed improvement recommendations Letter grade assessment (A-F) Benchmark comparisons Progress tracking ### CI/CD Integration - name: "api-linting" run: python scripts/api_linter.py openapi.json - name: "breaking-change-detection" run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json - name: "api-scorecard" run: python scripts/api_scorecard.py openapi.json ### Pre-commit Hooks #!/bin/bash python engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json if [ $? -ne 0 ]; then echo "API linting failed. Please fix the issues before committing." exit 1 fi ### Best Practices Summary Consistency First: Maintain consistent naming, response formats, and patterns Documentation: Provide comprehensive, up-to-date API documentation Versioning: Plan for evolution with clear versioning strategies Error Handling: Implement consistent, informative error responses Security: Build security into every layer of the API Performance: Design for scale and efficiency from the start Backward Compatibility: Minimize breaking changes and provide migration paths Testing: Implement comprehensive testing including contract testing Monitoring: Add observability for API usage and performance Developer Experience: Prioritize ease of use and clear documentation ### Common Anti-Patterns to Avoid Verb-based URLs: Use nouns for resources, not actions Inconsistent Response Formats: Maintain standard response structures Over-nesting: Avoid deeply nested resource hierarchies Ignoring HTTP Status Codes: Use appropriate status codes for different scenarios Poor Error Messages: Provide actionable, specific error information Missing Pagination: Always paginate list endpoints No Versioning Strategy: Plan for API evolution from day one Exposing Internal Structure: Design APIs for external consumption, not internal convenience Missing Rate Limiting: Protect your API from abuse and overload Inadequate Testing: Test all aspects including error cases and edge conditions ### Conclusion The API Design Reviewer skill provides a comprehensive framework for building, reviewing, and maintaining high-quality REST APIs. By following these guidelines and using the provided tools, development teams can create APIs that are consistent, well-documented, secure, and maintainable. Regular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle. ## Trust - Source: tencent - Verification: Indexed source record - Publisher: alirezarezvani - Version: 2.1.1 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-04-29T06:02:17.604Z - Expires at: 2026-05-06T06:02:17.604Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/api-design-reviewer) - [Send to Agent page](https://openagent3.xyz/skills/api-design-reviewer/agent) - [JSON manifest](https://openagent3.xyz/skills/api-design-reviewer/agent.json) - [Markdown brief](https://openagent3.xyz/skills/api-design-reviewer/agent.md) - [Download page](https://openagent3.xyz/downloads/api-design-reviewer)