Skip to content

hoavdc/CodexKit / skills/codexkit-api-design-reviewer

codexkit-api-design-reviewer

Unverified

Review REST and GraphQL API designs for consistency, usability, and best practices. Covers naming conventions, versioning strategy, error format, pagination, authentication patterns, and breaking change detection. Use when reviewing API specs, designing new APIs, or auditing existing endpoints.

API Design Reviewer

When to Use

  • When reviewing an OpenAPI/Swagger specification before implementation
  • When auditing existing API endpoints for consistency
  • When designing a new API from scratch
  • When preparing APIs for external/partner consumption

Procedure

Step 1 — Naming & Convention Check

CheckRuleExample
Resource namingPlural nouns, kebab-case✅ /api/v1/order-items ❌ /api/v1/getOrderItem
HTTP methodsGET=read, POST=create, PUT=replace, PATCH=partial, DELETE=remove✅ POST /orders ❌ POST /create-order
Query paramscamelCase for filters/sorting✅ ?sortBy=createdAt ❌ ?sort_by=created_at
Status codesUse standard codes correctly✅ 201 Created, 204 No Content ❌ 200 for everything
ConsistencySame pattern across all endpointsCheck all resources follow same naming

Step 2 — Versioning Strategy

StrategyWhen to UsePattern
URL pathSimple, widely adopted/api/v1/orders
HeaderCleaner URLs, harder to testAccept: application/vnd.api+json;version=1
Query paramEasy to test, but less RESTful/api/orders?version=1

Verify:

  • Version is present in all endpoints
  • Deprecation policy documented
  • Migration guide for version bumps

Step 3 — Error Format

Errors should follow a consistent structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      {
        "field": "email",
        "issue": "Invalid format",
        "expected": "Valid email address"
      }
    ],
    "request_id": "req_abc123",
    "docs_url": "https://docs.api.com/errors/VALIDATION_ERROR"
  }
}

Check:

  • Error format consistent across all endpoints
  • Machine-readable error codes (not just messages)
  • Request ID for traceability
  • No sensitive data in error responses

Step 4 — Pagination

PatternBest ForImplementation
Cursor-basedLarge datasets, real-time data?cursor=abc&limit=20
Offset-basedSimple lists, admin UIs?page=2&per_page=20
KeysetTime-series data?after=2024-03-15T00:00:00Z&limit=20

Check:

  • Default page size set (and documented)
  • Maximum page size enforced
  • Total count available (or explicitly omitted for performance)
  • Links to next/prev pages in response

Step 5 — Security Patterns

CheckDetails
AuthenticationBearer token, API key, OAuth2 — documented per endpoint
AuthorizationRole-based access noted per endpoint
Rate limitingHeaders: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Input validationMax lengths, allowed characters, type checking
CORSAppropriate origins, methods, headers

Step 6 — Breaking Change Detection

Identify potential breaking changes:

  • ❌ Removing a field from response
  • ❌ Changing a field type (string → integer)
  • ❌ Making an optional field required
  • ❌ Changing endpoint URL
  • ✅ Adding a new optional field
  • ✅ Adding a new endpoint
  • ✅ Adding a new optional query parameter

Inputs

InputRequiredFormat
API specificationYesOpenAPI/Swagger YAML/JSON or endpoint list
Business contextRecommendedWho consumes this API
Existing APIRecommendedFor breaking change detection

Output

## API Review — [API Name]

### Summary
**Endpoints reviewed:** 24 | **Issues found:** 8 | **Breaking changes:** 0

### Issues

| # | Severity | Category | Endpoint | Issue | Fix |
|---|----------|----------|----------|-------|-----|
| 1 | High | Naming | POST /createUser | Verb in URL | POST /users |
| 2 | Medium | Errors | All | No request_id | Add tracing ID |
| 3 | Low | Pagination | GET /logs | No max page size | Enforce limit ≤ 100 |

### Recommendations
[Summary of patterns to adopt or fix]

Definition of Done

  • Naming conventions checked across all endpoints
  • Versioning strategy reviewed
  • Error format consistency verified
  • Pagination patterns assessed
  • Security patterns checked
  • Breaking changes flagged

Quality Criteria

  • Feedback is specific and references exact locations in the reviewed material
  • Each critique includes a concrete improvement suggestion
  • Severity is categorized (critical / important / nice-to-have)
  • Positive aspects are acknowledged alongside areas for improvement

Verification (4C)

CheckQuestion
CorrectnessIs the feedback technically accurate and properly contextualized?
CompletenessWere all major sections of the reviewed material addressed?
Context-fitIs the review granularity appropriate for the material's maturity level?
ConsequenceIf the author implemented all feedback literally, what could go wrong?

Edge Cases

  • Material is too early-stage for detailed review — Provide structural feedback only. Note that content review is deferred until it matures.
  • Reviewer lacks domain expertise — Focus on structure, clarity, and consistency. Flag domain-specific claims as 'Needs SME verification'.
  • Author is defensive or resistant to feedback — Lead with what works well. Frame changes as questions rather than mandates.

Changelog

  • v1.0.0 — Initial release
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 464kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall