Skip to main content Skills Marketplace 커뮤니티가 만든 AI 스킬을 발견하고 탐색하세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/thiagofernandes1987-create/APEX --skill api-design-reviewer명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
Zip 다운로드 다운로드 중... 이 저장소의 다른 Skills Token-aware reasoning workflow with real tools: picks an operating mode to control cost, runs a structured pipeline (decompose → validate → verify → snapshot), and gives Claude Program-of-Thought, RK4/Euler, a code gate, and a safe skill router. Use when: multi-step or high-stakes tasks, real math, precise computation, audits, or the user mentions APEX, PoT, pipeline, or scientific mode.
agent-framework-azure-ai-py **v00.33.0**: Ingested from antigravity-awesome-skills community repo
run multiple local CLI agents in parallel (separate tmux sessions)
thiagofernandes1987-create
thiagofernandes1987-create/APEX
GitHub 저장소 열기 name api-design-reviewer description Use this skill when the task requires api design reviewer capabilities. executor HYBRID skill_id engineering.cs-engineering.api-design-reviewer status ADOPTED security {"level":"standard","pii":false,"approval_required":false} anchors ["engineering","api","design"] tier 2 input_schema [{"name":"code_or_task","type":"string","description":"Code snippet, script, or task description to process","required":true}] output_schema [{"name":"report","type":"string","description":"Analysis report or summary from api design reviewer"}]
API Design Reviewer
Tier: POWERFULCategory: Engineering / ArchitectureMaintainer: 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.
Core Capabilities
1. API Linting and Convention Analysis
Resource Naming Conventions : Enforces kebab-case for resources, camelCase for fieldsHTTP Method Usage : Validates proper use of GET, POST, PUT, PATCH, DELETEURL Structure : Analyzes endpoint patterns for consistency and RESTful designStatus Code Compliance : Ensures appropriate HTTP status codes are usedError Response Formats : Validates consistent error response structuresDocumentation Coverage : Checks for missing descriptions and documentation gaps
2. Breaking Change Detection
Endpoint Removal : Detects removed or deprecated endpointsResponse Shape Changes : Identifies modifications to response structuresField Removal : Tracks removed or renamed fields in API responsesType Changes : Catches field type modifications that could break clientsRequired Field Additions : Flags new required fields that could break existing integrationsStatus Code Changes : Detects changes to expected status codes
3. API Design Scoring and Assessment
Consistency Analysis (30%): Evaluates naming conventions, response patterns, and structural consistencyDocumentation Quality (20%): Assesses completeness and clarity of API documentationSecurity Implementation (20%): Reviews authentication, authorization, and security headersUsability Design (15%): Analyzes ease of use, discoverability, and developer experiencePerformance Patterns (15%): Evaluates caching, pagination, and efficiency patterns
REST Design Principles
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
Versioning Strategies
1. URL Versioning (Recommended) /api/v1/users
/api/v2/users
Pros : Clear, explicit, easy to routeCons : URL proliferation, caching complexity
2. Header Versioning GET /api/users
Accept: application/vnd.api+json;version=1
Pros : Clean URLs, content negotiationCons : Less visible, harder to test manually
3. Media Type Versioning GET /api/users
Accept: application/vnd.myapi.v1+json
Pros : RESTful, supports multiple representationsCons : Complex, harder to implement
4. Query Parameter Versioning Pros : Simple to implementCons : Not RESTful, can be ignored
Pagination Patterns
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
}
}
Error Response Formats
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 parameters401 Unauthorized : Authentication required403 Forbidden : Access denied (authenticated but not authorized)404 Not Found : Resource not found409 Conflict : Resource conflict (duplicate, version mismatch)422 Unprocessable Entity : Valid syntax but semantic errors429 Too Many Requests : Rate limit exceeded500 Internal Server Error : Unexpected server error
Authentication and Authorization Patterns
Bearer Token Authentication Authorization: Bearer <token>
API Key Authentication X-API-Key: <api-key>
Authorization: Api-Key <api-key>
OAuth 2.0 Flow Authorization: Bearer <oauth-access-token>
Role-Based Access Control (RBAC) {
"user" : {
"id" : "123" ,
"roles" : [ "admin" , "editor" ] ,
"permissions" : [ "read:users" , "write:orders" ]
}
}
Rate Limiting Implementation
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
}
}
HATEOAS (Hypermedia as the Engine of Application State)
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"
}
}
}
Idempotency
Idempotent Methods
GET : Always safe and idempotentPUT : 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
Backward Compatibility Guidelines
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
OpenAPI/Swagger Validation
Required Components
API Information : Title, description, versionServer Information : Base URLs and descriptionsPath Definitions : All endpoints with methodsParameter Definitions : Query, path, header parametersRequest/Response Schemas : Complete data modelsSecurity Definitions : Authentication schemesError 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
Performance Considerations
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)
Security Best Practices
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
Tools and Scripts
api_linter.py Analyzes API specifications for compliance with REST conventions and best practices.
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.
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.
Multi-dimensional scoring
Detailed improvement recommendations
Letter grade assessment (A-F)
Benchmark comparisons
Progress tracking
Integration Examples
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 patternsDocumentation : Provide comprehensive, up-to-date API documentationVersioning : Plan for evolution with clear versioning strategiesError Handling : Implement consistent, informative error responsesSecurity : Build security into every layer of the APIPerformance : Design for scale and efficiency from the startBackward Compatibility : Minimize breaking changes and provide migration pathsTesting : Implement comprehensive testing including contract testingMonitoring : Add observability for API usage and performanceDeveloper Experience : Prioritize ease of use and clear documentation
Common Anti-Patterns to Avoid
Verb-based URLs : Use nouns for resources, not actionsInconsistent Response Formats : Maintain standard response structuresOver-nesting : Avoid deeply nested resource hierarchiesIgnoring HTTP Status Codes : Use appropriate status codes for different scenariosPoor Error Messages : Provide actionable, specific error informationMissing Pagination : Always paginate list endpointsNo Versioning Strategy : Plan for API evolution from day oneExposing Internal Structure : Design APIs for external consumption, not internal convenienceMissing Rate Limiting : Protect your API from abuse and overloadInadequate 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.
Why This Skill Exists Implement — API Design Reviewer
When to Use Use this skill when the task requires api design reviewer capabilities.
What If Fails If this skill fails to produce the expected output: (1) verify input completeness, (2) retry with more specific context, (3) fall back to the parent workflow without this skill.
