api-design-reviewer

仓库: borghei/claude-skills
安装量: 43
排名: #17127

安装

npx skills add https://github.com/borghei/claude-skills --skill api-design-reviewer
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.
Core Capabilities
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
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 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
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 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
Authentication and Authorization Patterns
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"
]
}
}
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 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
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, 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 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. 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 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 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.
← 返回排行榜