Use when reviewing API designs for consistency, usability, versioning, error semantics, security, backward compatibility, and developer experience before implementation or release.
Use when reviewing API designs for consistency, usability, versioning, error semantics, security, backward compatibility, and developer experience before implementation or release.
zh_description
用于评审 API 设计的一致性、可用性、版本策略、错误语义、安全性和开发者体验。
version
1.0.0
author
seaworld008
source
in-house
source_url
tags
["api", "design", "development", "reviewer"]
created_at
2026-03-04
updated_at
2026-06-29
quality
5
complexity
intermediate
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":{"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
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.
