AGENT SKILL

api-design-reviewer

Comprehensive REST API design review with automated linting, breaking-change detection, and design scorecards. Catches inconsistent conventions, missing versioning, and design smells before APIs ship. Use when reviewing a PR that adds or changes API endpoints, auditing an existing API for v2 migration, or establishing API standards for a team.

License 许可
MIT
最近更新
2026-06-04
Stars
★ 2
Forks
0

01 前言 Front Matter

name
api-design-reviewer
description
Comprehensive REST API design review with automated linting, breaking-change detection, and design scorecards. Catches inconsistent conventions, missing versioning, and design smells before APIs ship. Use when reviewing a PR that adds or changes API endpoints, auditing an existing API for v2 migration, or establishing API standards for a team.

02 资源文件 5

03 SKILL.md 正文

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 <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 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

  1. Consistency First: Maintain consistent naming, response formats, and patterns
  2. Documentation: Provide comprehensive, up-to-date API documentation
  3. Versioning: Plan for evolution with clear versioning strategies
  4. Error Handling: Implement consistent, informative error responses
  5. Security: Build security into every layer of the API
  6. Performance: Design for scale and efficiency from the start
  7. Backward Compatibility: Minimize breaking changes and provide migration paths
  8. Testing: Implement comprehensive testing including contract testing
  9. Monitoring: Add observability for API usage and performance
  10. Developer Experience: Prioritize ease of use and clear documentation

Common Anti-Patterns to Avoid

  1. Verb-based URLs: Use nouns for resources, not actions
  2. Inconsistent Response Formats: Maintain standard response structures
  3. Over-nesting: Avoid deeply nested resource hierarchies
  4. Ignoring HTTP Status Codes: Use appropriate status codes for different scenarios
  5. Poor Error Messages: Provide actionable, specific error information
  6. Missing Pagination: Always paginate list endpoints
  7. No Versioning Strategy: Plan for API evolution from day one
  8. Exposing Internal Structure: Design APIs for external consumption, not internal convenience
  9. Missing Rate Limiting: Protect your API from abuse and overload
  10. 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.

04 同仓库更多 Skills

kruxshnx
kruxshnx/claude-skills-devin

syllabus

Generates a curated supplementary reading list from any course syllabus using Consensus academic search. Grill-me intake (syllabus input format + course audience + year range) plus a grouping forcing-options checkpoint before any search runs — so the reading list matches the course's level and recency need. Parses the syllabus to extract topics and learning outcomes, searches Consensus for recent peer-reviewed papers per topic, and produces a professionally formatted .docx with clickable Consensus links, plain-language summaries calibrated to audience level, and Bloom-higher-order discussion questions tied to course learning goals. Triggers whenever a user uploads a syllabus, course outline, or curriculum document and wants supplementary readings. Also triggers on: 'syllabus reading list', 'find papers for my course', 'create a reading list from this syllabus', 'recent research for my class', 'supplementary readings', 'find journal articles for these topics', 'what recent papers cover this material', 'any new research on these course topics', 'update my syllabus with recent papers'. Even casual mentions when a syllabus is attached should trigger this skill.

★ 2
kruxshnx
kruxshnx/claude-skills-devin

research

Default entry point for any research request — a hybrid router that classifies the question deterministically and either delegates to a specialist research skill (pulse for trends/sentiment, grants for NIH funding, litreview for academic literature, syllabus for course reading, patent for prior-art + IP landscape, dossier for entity research) or runs its own plan-decompose-multi-source-search-synthesize-cite fallback workflow when no specialist matches. Always surfaces the routing decision so users can override. Triggers — "research [topic]", "look into [topic]", "what do we know about [topic]", "investigate [topic]", "find me information on [topic]", "do some research on [topic]", "I need to understand [topic]", or any research request that doesn't obviously match a more-specific specialist skill. Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log.

★ 2
kruxshnx
kruxshnx/claude-skills-devin

pulse

Multi-source recency research skill that takes the pulse of any topic across Reddit, Hacker News, the open web, and optionally X/Twitter within a configurable recent window (default 30 days). Forcing intake clarifies topic specificity, angle (trend/sentiment/problems/opportunities/comparison), time window, and platform scope before searching. Returns a synthesized briefing with citations, engagement metrics, and cross-platform pattern analysis. Triggers: 'pulse on [topic]', 'what's happening with [topic]', 'what are people saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]', or any variation requesting multi-source recency intelligence on a topic. Also use for competitor research, trend discovery, tool comparisons, and audience sentiment analysis.

★ 2
kruxshnx
kruxshnx/claude-skills-devin

patent

Patent prior-art and landscape intelligence skill — not generic patent help. Commits to one of five sub-use-cases via forcing intake (novelty search / freedom-to-operate / competitive landscape / acquisition diligence / litigation prior-art) before any search runs. Searches Google Patents, Espacenet, USPTO, and optionally Lens.org for citation-graph signals. Output is an editable Word document (.docx) with verdict, ranked closest art (claim-text extracted), CPC-class-aware landscape, family-resolved hits, geographic coverage, FTO flags where applicable, strategy recommendations, and full audit log. Triggers: 'prior art search for [invention]', 'patent search on [topic]', 'freedom to operate analysis', 'FTO for [product]', 'patent landscape for [field]', 'is [invention] novel', 'patents on [topic]', 'competitive patent analysis', 'prior art for litigation', 'patent diligence on [company]'. Produces search signal, not legal advice — always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope.

★ 2
kruxshnx
kruxshnx/claude-skills-devin

notebooklm

Browser automation skill for controlling Google's NotebookLM. Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio Overview, infographics, slide decks, study guides, briefing docs, mind maps, timelines, FAQs), and creating new notebooks. Triggers on any phrase involving NotebookLM — 'open NotebookLM', 'check my [name] notebook', 'pull info from NotebookLM', 'ask my notebook about X', 'add [source] to NotebookLM', 'create an infographic in NotebookLM', 'use NotebookLM Studio', 'generate a slide deck from my notebook', or any variation where the goal involves NotebookLM. Requires browser automation environment — fails gracefully when unavailable.

★ 2
kruxshnx
kruxshnx/claude-skills-devin

litreview

Academic literature orientation skill that searches papers via Consensus, builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a professionally formatted Word document (.docx) research guide. Grill-me intake (research question specificity + framework hint + tentative depth) before the recon search; a second forcing checkpoint after Phase 2 confirms framework + sub-areas + depth before searches consume budget. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' — not a finished review, but an orientation guide that lets a researcher dive in confidently. Triggers: 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'. Do NOT trigger for single one-off paper searches where the user just wants a quick list — that's a plain Consensus search.

★ 2