home / skills / shotaiuchi / dotclaude / review-api-design

review-api-design skill

safe

This skill reviews API design and contract quality across REST, GraphQL, and SDK surfaces to improve usability and backward compatibility.

npx playbooks add skill shotaiuchi/dotclaude --skill review-api-design

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.1 KB

---
name: review-api-design
description: >-
  API design and contract-focused code review. Apply when reviewing
  REST APIs, GraphQL schemas, SDK interfaces, public function signatures,
  versioning, backward compatibility, and API documentation.
user-invocable: false
---

# API Design Review

Review code from an API design and contract perspective.

## Review Checklist

### Naming & Consistency
- Verify endpoint/method naming follows conventions
- Check parameter naming is clear and unambiguous
- Ensure consistent patterns across similar endpoints
- Verify HTTP methods match semantics (GET=read, POST=create, etc.)

### Request & Response Design
- Check request payloads are minimal and well-structured
- Verify response shapes are consistent across endpoints
- Ensure pagination is implemented for list endpoints
- Check filtering/sorting capabilities where needed

### Error Responses
- Verify error response format is consistent and documented
- Check HTTP status codes are semantically correct
- Ensure error messages are helpful without leaking internals
- Verify validation errors include field-level detail

### Versioning & Compatibility
- Check for breaking changes to existing contracts
- Verify backward compatibility is maintained
- Look for required fields that should be optional
- Check deprecation is properly signaled

### Documentation & Discoverability
- Verify API documentation is accurate and complete
- Check request/response examples are provided
- Ensure required vs optional parameters are clear
- Verify authentication/authorization requirements are documented

### Rate Limiting & Quotas
- Check rate limiting is applied to public endpoints
- Verify appropriate limits for different client tiers
- Ensure rate limit headers are included in responses
- Check bulk endpoints have payload size limits

## Output Format

| Category | Description |
|----------|-------------|
| Breaking | Change breaks existing clients |
| Design | API design issue affecting usability |
| Contract | Missing or ambiguous contract definition |
| Enhancement | Improvement for better developer experience |

Overview

This skill performs API design and contract-focused code reviews to catch issues before they reach clients. It evaluates REST endpoints, GraphQL schemas, SDK interfaces, and public function signatures for clarity, consistency, and backward compatibility. The goal is to reduce integration friction and prevent breaking changes.

How this skill works

I inspect endpoint and operation naming, HTTP methods, request/response payloads, error formats, and versioning signals. I look for consistent shapes, pagination and filtering support, documented examples, and appropriate rate-limiting behavior. Findings are categorized as Breaking, Design, Contract, or Enhancement to guide prioritization.

When to use it

Before merging API changes that affect public endpoints or SDKs
When adding new endpoints, mutations, or response fields
When changing request/response shapes or renaming parameters
During API version planning or deprecation rollout
When auditing documentation, examples, and error formats

Best practices

Use consistent, intent-revealing names and align HTTP methods with semantics
Keep request payloads minimal; prefer explicit field contracts and stable response shapes
Implement pagination for list endpoints and expose filtering/sorting options
Standardize error responses with HTTP codes and field-level validation details
Signal breaking changes and deprecations clearly; avoid required fields that break clients
Document auth, rate limits, examples, and required vs optional parameters

Example use cases

Reviewing a PR that renames response fields to ensure backward compatibility
Auditing a GraphQL schema for ambiguous input types and missing error handling
Validating a public SDK update to ensure method names and signatures are stable
Checking an API surface for missing pagination, inconsistent filtering, or undocumented headers
Assessing a deprecation plan to confirm clients have migration paths and versioning signals

FAQ

How do you decide if a change is Breaking vs Design?

A Breaking issue changes the contract clients rely on (renamed/removed fields, altered types, or behavioral changes). Design covers usability or consistency problems that don't immediately break clients.

Do you validate runtime behavior or only interfaces?

Focus is on contracts and design. I review schemas, signatures, examples, and docs. Runtime testing and performance checks should be added separately.