{ "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": { "downloadMode": "redirect", "downloadUrl": "/downloads/api-design-reviewer", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-design-reviewer", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "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" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "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." ], "prompts": [ { "label": "New install", "body": "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." }, { "label": "Upgrade existing", "body": "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." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-23T16:43:11.935Z", "expiresAt": "2026-04-30T16:43:11.935Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "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." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/api-design-reviewer", "agentPageUrl": "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" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "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." ], "prompts": [ { "label": "New install", "body": "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." }, { "label": "Upgrade existing", "body": "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." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "API Design Reviewer", "body": "Tier: POWERFUL\nCategory: Engineering / Architecture\nMaintainer: Claude Skills Team" }, { "title": "Overview", "body": "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." }, { "title": "1. API Linting and Convention Analysis", "body": "Resource Naming Conventions: Enforces kebab-case for resources, camelCase for fields\nHTTP Method Usage: Validates proper use of GET, POST, PUT, PATCH, DELETE\nURL Structure: Analyzes endpoint patterns for consistency and RESTful design\nStatus Code Compliance: Ensures appropriate HTTP status codes are used\nError Response Formats: Validates consistent error response structures\nDocumentation Coverage: Checks for missing descriptions and documentation gaps" }, { "title": "2. Breaking Change Detection", "body": "Endpoint Removal: Detects removed or deprecated endpoints\nResponse Shape Changes: Identifies modifications to response structures\nField Removal: Tracks removed or renamed fields in API responses\nType Changes: Catches field type modifications that could break clients\nRequired Field Additions: Flags new required fields that could break existing integrations\nStatus Code Changes: Detects changes to expected status codes" }, { "title": "3. API Design Scoring and Assessment", "body": "Consistency Analysis (30%): Evaluates naming conventions, response patterns, and structural consistency\nDocumentation Quality (20%): Assesses completeness and clarity of API documentation\nSecurity Implementation (20%): Reviews authentication, authorization, and security headers\nUsability Design (15%): Analyzes ease of use, discoverability, and developer experience\nPerformance Patterns (15%): Evaluates caching, pagination, and efficiency patterns" }, { "title": "Resource Naming Conventions", "body": "✅ Good Examples:\n- /api/v1/users\n- /api/v1/user-profiles\n- /api/v1/orders/123/line-items\n\n❌ Bad Examples:\n- /api/v1/getUsers\n- /api/v1/user_profiles\n- /api/v1/orders/123/lineItems" }, { "title": "HTTP Method Usage", "body": "GET: Retrieve resources (safe, idempotent)\nPOST: Create new resources (not idempotent)\nPUT: Replace entire resources (idempotent)\nPATCH: Partial resource updates (not necessarily idempotent)\nDELETE: Remove resources (idempotent)" }, { "title": "URL Structure Best Practices", "body": "Collection Resources: /api/v1/users\nIndividual Resources: /api/v1/users/123\nNested Resources: /api/v1/users/123/orders\nActions: /api/v1/users/123/activate (POST)\nFiltering: /api/v1/users?status=active&role=admin" }, { "title": "1. URL Versioning (Recommended)", "body": "/api/v1/users\n/api/v2/users\n\nPros: Clear, explicit, easy to route\nCons: URL proliferation, caching complexity" }, { "title": "2. Header Versioning", "body": "GET /api/users\nAccept: application/vnd.api+json;version=1\n\nPros: Clean URLs, content negotiation\nCons: Less visible, harder to test manually" }, { "title": "3. Media Type Versioning", "body": "GET /api/users\nAccept: application/vnd.myapi.v1+json\n\nPros: RESTful, supports multiple representations\nCons: Complex, harder to implement" }, { "title": "4. Query Parameter Versioning", "body": "/api/users?version=1\n\nPros: Simple to implement\nCons: Not RESTful, can be ignored" }, { "title": "Offset-Based Pagination", "body": "{\n \"data\": [...],\n \"pagination\": {\n \"offset\": 20,\n \"limit\": 10,\n \"total\": 150,\n \"hasMore\": true\n }\n}" }, { "title": "Cursor-Based Pagination", "body": "{\n \"data\": [...],\n \"pagination\": {\n \"nextCursor\": \"eyJpZCI6MTIzfQ==\",\n \"hasMore\": true\n }\n}" }, { "title": "Page-Based Pagination", "body": "{\n \"data\": [...],\n \"pagination\": {\n \"page\": 3,\n \"pageSize\": 10,\n \"totalPages\": 15,\n \"totalItems\": 150\n }\n}" }, { "title": "Standard Error Structure", "body": "{\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"The request contains invalid parameters\",\n \"details\": [\n {\n \"field\": \"email\",\n \"code\": \"INVALID_FORMAT\",\n \"message\": \"Email address is not valid\"\n }\n ],\n \"requestId\": \"req-123456\",\n \"timestamp\": \"2024-02-16T13:00:00Z\"\n }\n}" }, { "title": "HTTP Status Code Usage", "body": "400 Bad Request: Invalid request syntax or parameters\n401 Unauthorized: Authentication required\n403 Forbidden: Access denied (authenticated but not authorized)\n404 Not Found: Resource not found\n409 Conflict: Resource conflict (duplicate, version mismatch)\n422 Unprocessable Entity: Valid syntax but semantic errors\n429 Too Many Requests: Rate limit exceeded\n500 Internal Server Error: Unexpected server error" }, { "title": "Bearer Token Authentication", "body": "Authorization: Bearer " }, { "title": "API Key Authentication", "body": "X-API-Key: \nAuthorization: Api-Key " }, { "title": "OAuth 2.0 Flow", "body": "Authorization: Bearer " }, { "title": "Role-Based Access Control (RBAC)", "body": "{\n \"user\": {\n \"id\": \"123\",\n \"roles\": [\"admin\", \"editor\"],\n \"permissions\": [\"read:users\", \"write:orders\"]\n }\n}" }, { "title": "Headers", "body": "X-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 999\nX-RateLimit-Reset: 1640995200" }, { "title": "Response on Limit Exceeded", "body": "{\n \"error\": {\n \"code\": \"RATE_LIMIT_EXCEEDED\",\n \"message\": \"Too many requests\",\n \"retryAfter\": 3600\n }\n}" }, { "title": "Example Implementation", "body": "{\n \"id\": \"123\",\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"_links\": {\n \"self\": { \"href\": \"/api/v1/users/123\" },\n \"orders\": { \"href\": \"/api/v1/users/123/orders\" },\n \"profile\": { \"href\": \"/api/v1/users/123/profile\" },\n \"deactivate\": { \n \"href\": \"/api/v1/users/123/deactivate\",\n \"method\": \"POST\"\n }\n }\n}" }, { "title": "Idempotent Methods", "body": "GET: Always safe and idempotent\nPUT: Should be idempotent (replace entire resource)\nDELETE: Should be idempotent (same result)\nPATCH: May or may not be idempotent" }, { "title": "Idempotency Keys", "body": "POST /api/v1/payments\nIdempotency-Key: 123e4567-e89b-12d3-a456-426614174000" }, { "title": "Safe Changes (Non-Breaking)", "body": "Adding optional fields to requests\nAdding fields to responses\nAdding new endpoints\nMaking required fields optional\nAdding new enum values (with graceful handling)" }, { "title": "Breaking Changes (Require Version Bump)", "body": "Removing fields from responses\nMaking optional fields required\nChanging field types\nRemoving endpoints\nChanging URL structures\nModifying error response formats" }, { "title": "Required Components", "body": "API Information: Title, description, version\nServer Information: Base URLs and descriptions\nPath Definitions: All endpoints with methods\nParameter Definitions: Query, path, header parameters\nRequest/Response Schemas: Complete data models\nSecurity Definitions: Authentication schemes\nError Responses: Standard error formats" }, { "title": "Best Practices", "body": "Use consistent naming conventions\nProvide detailed descriptions for all components\nInclude examples for complex objects\nDefine reusable components and schemas\nValidate against OpenAPI specification" }, { "title": "Caching Strategies", "body": "Cache-Control: public, max-age=3600\nETag: \"123456789\"\nLast-Modified: Wed, 21 Oct 2015 07:28:00 GMT" }, { "title": "Efficient Data Transfer", "body": "Use appropriate HTTP methods\nImplement field selection (?fields=id,name,email)\nSupport compression (gzip)\nImplement efficient pagination\nUse ETags for conditional requests" }, { "title": "Resource Optimization", "body": "Avoid N+1 queries\nImplement batch operations\nUse async processing for heavy operations\nSupport partial updates (PATCH)" }, { "title": "Input Validation", "body": "Validate all input parameters\nSanitize user data\nUse parameterized queries\nImplement request size limits" }, { "title": "Authentication Security", "body": "Use HTTPS everywhere\nImplement secure token storage\nSupport token expiration and refresh\nUse strong authentication mechanisms" }, { "title": "Authorization Controls", "body": "Implement principle of least privilege\nUse resource-based permissions\nSupport fine-grained access control\nAudit access patterns" }, { "title": "api_linter.py", "body": "Analyzes API specifications for compliance with REST conventions and best practices.\n\nFeatures:\n\nOpenAPI/Swagger spec validation\nNaming convention checks\nHTTP method usage validation\nError format consistency\nDocumentation completeness analysis" }, { "title": "breaking_change_detector.py", "body": "Compares API specification versions to identify breaking changes.\n\nFeatures:\n\nEndpoint comparison\nSchema change detection\nField removal/modification tracking\nMigration guide generation\nImpact severity assessment" }, { "title": "api_scorecard.py", "body": "Provides comprehensive scoring of API design quality.\n\nFeatures:\n\nMulti-dimensional scoring\nDetailed improvement recommendations\nLetter grade assessment (A-F)\nBenchmark comparisons\nProgress tracking" }, { "title": "CI/CD Integration", "body": "- name: \"api-linting\"\n run: python scripts/api_linter.py openapi.json\n\n- name: \"breaking-change-detection\"\n run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json\n\n- name: \"api-scorecard\"\n run: python scripts/api_scorecard.py openapi.json" }, { "title": "Pre-commit Hooks", "body": "#!/bin/bash\npython engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json\nif [ $? -ne 0 ]; then\n echo \"API linting failed. Please fix the issues before committing.\"\n exit 1\nfi" }, { "title": "Best Practices Summary", "body": "Consistency First: Maintain consistent naming, response formats, and patterns\nDocumentation: Provide comprehensive, up-to-date API documentation\nVersioning: Plan for evolution with clear versioning strategies\nError Handling: Implement consistent, informative error responses\nSecurity: Build security into every layer of the API\nPerformance: Design for scale and efficiency from the start\nBackward Compatibility: Minimize breaking changes and provide migration paths\nTesting: Implement comprehensive testing including contract testing\nMonitoring: Add observability for API usage and performance\nDeveloper Experience: Prioritize ease of use and clear documentation" }, { "title": "Common Anti-Patterns to Avoid", "body": "Verb-based URLs: Use nouns for resources, not actions\nInconsistent Response Formats: Maintain standard response structures\nOver-nesting: Avoid deeply nested resource hierarchies\nIgnoring HTTP Status Codes: Use appropriate status codes for different scenarios\nPoor Error Messages: Provide actionable, specific error information\nMissing Pagination: Always paginate list endpoints\nNo Versioning Strategy: Plan for API evolution from day one\nExposing Internal Structure: Design APIs for external consumption, not internal convenience\nMissing Rate Limiting: Protect your API from abuse and overload\nInadequate Testing: Test all aspects including error cases and edge conditions" }, { "title": "Conclusion", "body": "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.\n\nRegular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle." } ], "body": "API Design Reviewer\n\nTier: POWERFUL\nCategory: Engineering / Architecture\nMaintainer: Claude Skills Team\n\nOverview\n\nThe 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.\n\nCore Capabilities\n1. API Linting and Convention Analysis\nResource Naming Conventions: Enforces kebab-case for resources, camelCase for fields\nHTTP Method Usage: Validates proper use of GET, POST, PUT, PATCH, DELETE\nURL Structure: Analyzes endpoint patterns for consistency and RESTful design\nStatus Code Compliance: Ensures appropriate HTTP status codes are used\nError Response Formats: Validates consistent error response structures\nDocumentation Coverage: Checks for missing descriptions and documentation gaps\n2. Breaking Change Detection\nEndpoint Removal: Detects removed or deprecated endpoints\nResponse Shape Changes: Identifies modifications to response structures\nField Removal: Tracks removed or renamed fields in API responses\nType Changes: Catches field type modifications that could break clients\nRequired Field Additions: Flags new required fields that could break existing integrations\nStatus Code Changes: Detects changes to expected status codes\n3. API Design Scoring and Assessment\nConsistency Analysis (30%): Evaluates naming conventions, response patterns, and structural consistency\nDocumentation Quality (20%): Assesses completeness and clarity of API documentation\nSecurity Implementation (20%): Reviews authentication, authorization, and security headers\nUsability Design (15%): Analyzes ease of use, discoverability, and developer experience\nPerformance Patterns (15%): Evaluates caching, pagination, and efficiency patterns\nREST Design Principles\nResource Naming Conventions\n✅ Good Examples:\n- /api/v1/users\n- /api/v1/user-profiles\n- /api/v1/orders/123/line-items\n\n❌ Bad Examples:\n- /api/v1/getUsers\n- /api/v1/user_profiles\n- /api/v1/orders/123/lineItems\n\nHTTP Method Usage\nGET: Retrieve resources (safe, idempotent)\nPOST: Create new resources (not idempotent)\nPUT: Replace entire resources (idempotent)\nPATCH: Partial resource updates (not necessarily idempotent)\nDELETE: Remove resources (idempotent)\nURL Structure Best Practices\nCollection Resources: /api/v1/users\nIndividual Resources: /api/v1/users/123\nNested Resources: /api/v1/users/123/orders\nActions: /api/v1/users/123/activate (POST)\nFiltering: /api/v1/users?status=active&role=admin\n\nVersioning Strategies\n1. URL Versioning (Recommended)\n/api/v1/users\n/api/v2/users\n\n\nPros: Clear, explicit, easy to route\nCons: URL proliferation, caching complexity\n\n2. Header Versioning\nGET /api/users\nAccept: application/vnd.api+json;version=1\n\n\nPros: Clean URLs, content negotiation\nCons: Less visible, harder to test manually\n\n3. Media Type Versioning\nGET /api/users\nAccept: application/vnd.myapi.v1+json\n\n\nPros: RESTful, supports multiple representations\nCons: Complex, harder to implement\n\n4. Query Parameter Versioning\n/api/users?version=1\n\n\nPros: Simple to implement\nCons: Not RESTful, can be ignored\n\nPagination Patterns\nOffset-Based Pagination\n{\n \"data\": [...],\n \"pagination\": {\n \"offset\": 20,\n \"limit\": 10,\n \"total\": 150,\n \"hasMore\": true\n }\n}\n\nCursor-Based Pagination\n{\n \"data\": [...],\n \"pagination\": {\n \"nextCursor\": \"eyJpZCI6MTIzfQ==\",\n \"hasMore\": true\n }\n}\n\nPage-Based Pagination\n{\n \"data\": [...],\n \"pagination\": {\n \"page\": 3,\n \"pageSize\": 10,\n \"totalPages\": 15,\n \"totalItems\": 150\n }\n}\n\nError Response Formats\nStandard Error Structure\n{\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"The request contains invalid parameters\",\n \"details\": [\n {\n \"field\": \"email\",\n \"code\": \"INVALID_FORMAT\",\n \"message\": \"Email address is not valid\"\n }\n ],\n \"requestId\": \"req-123456\",\n \"timestamp\": \"2024-02-16T13:00:00Z\"\n }\n}\n\nHTTP Status Code Usage\n400 Bad Request: Invalid request syntax or parameters\n401 Unauthorized: Authentication required\n403 Forbidden: Access denied (authenticated but not authorized)\n404 Not Found: Resource not found\n409 Conflict: Resource conflict (duplicate, version mismatch)\n422 Unprocessable Entity: Valid syntax but semantic errors\n429 Too Many Requests: Rate limit exceeded\n500 Internal Server Error: Unexpected server error\nAuthentication and Authorization Patterns\nBearer Token Authentication\nAuthorization: Bearer \n\nAPI Key Authentication\nX-API-Key: \nAuthorization: Api-Key \n\nOAuth 2.0 Flow\nAuthorization: Bearer \n\nRole-Based Access Control (RBAC)\n{\n \"user\": {\n \"id\": \"123\",\n \"roles\": [\"admin\", \"editor\"],\n \"permissions\": [\"read:users\", \"write:orders\"]\n }\n}\n\nRate Limiting Implementation\nHeaders\nX-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 999\nX-RateLimit-Reset: 1640995200\n\nResponse on Limit Exceeded\n{\n \"error\": {\n \"code\": \"RATE_LIMIT_EXCEEDED\",\n \"message\": \"Too many requests\",\n \"retryAfter\": 3600\n }\n}\n\nHATEOAS (Hypermedia as the Engine of Application State)\nExample Implementation\n{\n \"id\": \"123\",\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"_links\": {\n \"self\": { \"href\": \"/api/v1/users/123\" },\n \"orders\": { \"href\": \"/api/v1/users/123/orders\" },\n \"profile\": { \"href\": \"/api/v1/users/123/profile\" },\n \"deactivate\": { \n \"href\": \"/api/v1/users/123/deactivate\",\n \"method\": \"POST\"\n }\n }\n}\n\nIdempotency\nIdempotent Methods\nGET: Always safe and idempotent\nPUT: Should be idempotent (replace entire resource)\nDELETE: Should be idempotent (same result)\nPATCH: May or may not be idempotent\nIdempotency Keys\nPOST /api/v1/payments\nIdempotency-Key: 123e4567-e89b-12d3-a456-426614174000\n\nBackward Compatibility Guidelines\nSafe Changes (Non-Breaking)\nAdding optional fields to requests\nAdding fields to responses\nAdding new endpoints\nMaking required fields optional\nAdding new enum values (with graceful handling)\nBreaking Changes (Require Version Bump)\nRemoving fields from responses\nMaking optional fields required\nChanging field types\nRemoving endpoints\nChanging URL structures\nModifying error response formats\nOpenAPI/Swagger Validation\nRequired Components\nAPI Information: Title, description, version\nServer Information: Base URLs and descriptions\nPath Definitions: All endpoints with methods\nParameter Definitions: Query, path, header parameters\nRequest/Response Schemas: Complete data models\nSecurity Definitions: Authentication schemes\nError Responses: Standard error formats\nBest Practices\nUse consistent naming conventions\nProvide detailed descriptions for all components\nInclude examples for complex objects\nDefine reusable components and schemas\nValidate against OpenAPI specification\nPerformance Considerations\nCaching Strategies\nCache-Control: public, max-age=3600\nETag: \"123456789\"\nLast-Modified: Wed, 21 Oct 2015 07:28:00 GMT\n\nEfficient Data Transfer\nUse appropriate HTTP methods\nImplement field selection (?fields=id,name,email)\nSupport compression (gzip)\nImplement efficient pagination\nUse ETags for conditional requests\nResource Optimization\nAvoid N+1 queries\nImplement batch operations\nUse async processing for heavy operations\nSupport partial updates (PATCH)\nSecurity Best Practices\nInput Validation\nValidate all input parameters\nSanitize user data\nUse parameterized queries\nImplement request size limits\nAuthentication Security\nUse HTTPS everywhere\nImplement secure token storage\nSupport token expiration and refresh\nUse strong authentication mechanisms\nAuthorization Controls\nImplement principle of least privilege\nUse resource-based permissions\nSupport fine-grained access control\nAudit access patterns\nTools and Scripts\napi_linter.py\n\nAnalyzes API specifications for compliance with REST conventions and best practices.\n\nFeatures:\n\nOpenAPI/Swagger spec validation\nNaming convention checks\nHTTP method usage validation\nError format consistency\nDocumentation completeness analysis\nbreaking_change_detector.py\n\nCompares API specification versions to identify breaking changes.\n\nFeatures:\n\nEndpoint comparison\nSchema change detection\nField removal/modification tracking\nMigration guide generation\nImpact severity assessment\napi_scorecard.py\n\nProvides comprehensive scoring of API design quality.\n\nFeatures:\n\nMulti-dimensional scoring\nDetailed improvement recommendations\nLetter grade assessment (A-F)\nBenchmark comparisons\nProgress tracking\nIntegration Examples\nCI/CD Integration\n- name: \"api-linting\"\n run: python scripts/api_linter.py openapi.json\n\n- name: \"breaking-change-detection\"\n run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json\n\n- name: \"api-scorecard\"\n run: python scripts/api_scorecard.py openapi.json\n\nPre-commit Hooks\n#!/bin/bash\npython engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json\nif [ $? -ne 0 ]; then\n echo \"API linting failed. Please fix the issues before committing.\"\n exit 1\nfi\n\nBest Practices Summary\nConsistency First: Maintain consistent naming, response formats, and patterns\nDocumentation: Provide comprehensive, up-to-date API documentation\nVersioning: Plan for evolution with clear versioning strategies\nError Handling: Implement consistent, informative error responses\nSecurity: Build security into every layer of the API\nPerformance: Design for scale and efficiency from the start\nBackward Compatibility: Minimize breaking changes and provide migration paths\nTesting: Implement comprehensive testing including contract testing\nMonitoring: Add observability for API usage and performance\nDeveloper Experience: Prioritize ease of use and clear documentation\nCommon Anti-Patterns to Avoid\nVerb-based URLs: Use nouns for resources, not actions\nInconsistent Response Formats: Maintain standard response structures\nOver-nesting: Avoid deeply nested resource hierarchies\nIgnoring HTTP Status Codes: Use appropriate status codes for different scenarios\nPoor Error Messages: Provide actionable, specific error information\nMissing Pagination: Always paginate list endpoints\nNo Versioning Strategy: Plan for API evolution from day one\nExposing Internal Structure: Design APIs for external consumption, not internal convenience\nMissing Rate Limiting: Protect your API from abuse and overload\nInadequate Testing: Test all aspects including error cases and edge conditions\nConclusion\n\nThe 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.\n\nRegular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle." }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/alirezarezvani/api-design-reviewer", "publisherUrl": "https://clawhub.ai/alirezarezvani/api-design-reviewer", "owner": "alirezarezvani", "version": "2.1.1", "license": null, "verificationStatus": "Indexed source record" }, "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" } }