Skip to content
Skills Library
Programming · Review & audit

api-design-review

/api-design-review

Review an API contract (REST or GraphQL) before or while it is implemented, checking resource naming, HTTP semantics, status codes, error shape, pagination, versioning, idempotency, and backward compatibility, and producing concrete revisions rather than abstract advice. Use when designing new endpoints, changing an existing API's surface, or reviewing a PR that adds or modifies API routes.

Repository
dotclaude ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Review an API contract (REST or GraphQL) before or while it is implemented, checking resource naming, HTTP semantics, status codes, error shape, pagination, versioning, idempotency, and backward compatibility, and producing concrete revisions rather than abstract advice. Use when designing new endpoints, changing an existing API's surface, or reviewing a PR that adds or modifies API routes.

Original author description

Review an API contract (REST or GraphQL) before or while it is implemented, checking resource naming, HTTP semantics, status codes, error shape, pagination, versioning, idempotency, and backward compatibility, and producing concrete revisions rather than abstract advice. Use when designing new endpoints, changing an existing API's surface, or reviewing a PR that adds or modifies API routes.

How it works

  1. Step 1: Establish the existing contract
  2. Step 2: Review the surface
  3. Step 3: Report
Original SKILL.md headings · 48 lines, 589 words
SKILL.md preview
---
name: api-design-review
title: API Design Review
description: Review an API contract (REST or GraphQL) before or while it is implemented, checking resource naming, HTTP semantics, status codes, error shape, pagination, versioning, idempotency, and backward compatibility, and producing concrete revisions rather than abstract advice. Use when designing new endpoints, changing an existing API's surface, or reviewing a PR that adds or modifies API routes.
---

An API contract is the hardest thing in a codebase to change once someone depends on it. Review it as a future consumer under pressure: every inconsistency you let through becomes a permanent workaround in every client. Ground each finding in the project's existing conventions first; consistency with the API a team already ships beats textbook purity.

## Step 1: Establish the existing contract

Before judging anything, learn what this API already does:

- Find the existing routes/resolvers and read three or four representative ones end to end (path, verbs, request/response shapes, error handling).
- Find the conventions: error envelope shape, pagination style, naming case (camelCase vs snake_case), plural vs singular resources, auth mechanism, versioning scheme (path, header, or none).
- Find any OpenAPI/GraphQL schema, API docs, or client SDKs; those are the contract's consumers-eye view.

New surface must match these unless there is a stated reason to diverge, and divergence should be raised as its own finding.

## Step 2: Review the surface

Work through the checklist against each new or changed endpoint. Flag only what is wrong or risky, with the concrete revision.

**Resources and naming**
- Nouns for resources, verbs only via HTTP methods (`POST /orders`, not `POST /createOrder`). Sub-resources for ownership (`/users/{id}/orders`), not query-parameter relationships.
- Consistent casing and pluralization with the rest of the API.

**HTTP semantics**
- GET is safe and cacheable, never mutates. PUT is full replace and idempotent; PATCH is partial. DELETE is idempotent (second call returns the same outcome, 404 or 204, deliberately chosen).
- Status codes carry meaning: 201 + Location for creation, 400 for malformed input vs 422 for valid-but-unprocessable (pick the project's existing convention), 401 unauthenticated vs 403 unauthorized, 409 for conflicts, 429 with Retry-After for rate limits. Never 200 with an error in the body.

**Errors**
- One error envelope everywhere, machine-distinguishable (a stable `code` field, not just prose), with enough detail to act on but no internals (no stack traces, no SQL, no infrastructure hostnames).
- Validation errors name the field that failed.

**Collections**
- Pagination from day one on anything that can grow; cursor-based when ordering is stable and data is written concurrently, offset only for small or static sets. Response includes what the client needs to continue (next cursor / total when affordable).
- Filtering and sorting parameters validated against an allowlist, never passed through to the datastore.

**Change safety**
- Additive changes only within a version: new optional fields are fine; renaming, removing, retyping, or changing the meaning of an existing field is a break and needs a version bump or a deprecation path.
- Unknown fields in requests: decide and document ignore-vs-reject; do not leave it to framework defaults.

**Write safety**
- Mutations that a client might retry (payments, orders, anything POST) accept an idempotency key or are documented as at-most-once.
- Bulk operations define partial-failure behavior explicitly (all-or-nothing, or per-item results).

**GraphQL specifics** (when applicable)
- Nullability is a contract decision, not the schema default. Mutations return payload types with typed user errors, not thrown exceptions. Depth/complexity limits exist for public schemas. Pagination follows the connection pattern already in use.

## Step 3: Report

Order findings by cost-to-fix-later, not by section: contract breaks and irreversible naming first, then semantics, then polish. For each: what, where, why it will hurt, and the exact revised shape (show the corrected route/field/response, not a description of it). Close with anything that should be decided now but deferred deliberately, e.g. rate limiting or versioning strategy, so it is a recorded decision instead of an accident.

Versions

RepositoryScoreLicence
This page · khaledsaeed18/dotclaude90MIT
dotslashsimran/simcraft100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 773453ad72d5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 85backend-api-design-review
    Use when reviewing REST/HTTP or GraphQL APIs for resource modeling, HTTP method semantics, status codes, idempotency, versioning, error response shape, and pagination. Triggers when controllers/handlers/resolvers are in scope.
  • 95api-design
    REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning.
  • 95api-design
    REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning.
  • 100api-design
    REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning.
  • 100api-design
    REST and GraphQL API design covering resource modeling, status codes, error contracts, pagination, versioning, and evolution. Use to design or review an API.
  • 95api-design
    REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.