Api design

Skill byerlikaya/claude-starter-kit/plugin/skills/api-design

Enterprise engineering workflow for Claude Code — not just prompts. AI agents that plan, build, audit, and ship with security gates, privacy checks, and approval-controlled commits. Safely adopt it into new or existing repositories.

Install

npx -y skills add byerlikaya/claude-starter-kit --skill api-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

20 stars20 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

API contract design: resource naming, error model, versioning, pagination, backward compatibility, OpenAPI. A predictable interface that evolves without breaking consumers. Trigger phrases: "api design", "api contract", "api versioning", "openapi", "swagger", "rest contract", "breaking api change"

SKILL.md

3.0 KB, as published. Nobody here has run it

API Design

Goal: a contract the consumer can predict and that can evolve without breaking. Once published, a public API is a commitment; a breaking change is expensive. Stack-agnostic (REST as the baseline; GraphQL/gRPC follow similar principles).

Checklist

Resource names are consistent (plural nouns, a single kebab/camel style), resources not verbs
Correct HTTP semantics: GET (side-effect free) · POST · PUT/PATCH · DELETE; correct status code
A uniform error model: machine-readable code + human message + (if any) field details
A clear versioning strategy (URL /v1 or header); a breaking change means a new version
Pagination/filtering/sorting defined and consistent on large collections
Backward compatibility: adding a field is additive; removing a field or changing its meaning is breaking → version
Idempotency (for POST/payment-like cases) supported via a key when needed
The contract is documented in OpenAPI; example request/response present (coordinate with docs-writer)

How

Model the resource — a noun not a verb: POST /orders (✓), POST /createOrder (✗).
Status codes: 200/201/204 · 400 validation · 401/403 authorization · 404 · 409 conflict · 422 · 429 · 5xx. Use them meaningfully.
Error contract — every error has the same shape:
```
{ "code": "ORDER_NOT_FOUND", "message": "Order not found", "details": [] }
```
No stack trace / internal detail leakage (overlaps with security-scan).
Versioning: additive changes in the same version; breaking (remove/rename a field / add a required field) → /v2.
Collection: pagination (cursor or offset), filter/sort parameters; a consistent envelope.
Write the contract — OpenAPI/schema; with examples. Wire the change to docs-writer, and if breaking to release/CHANGELOG.

Breaking vs additive

Additive (safe)	Breaking (needs a version)
Add an optional field/endpoint	Remove / rename a field
A new optional parameter	Add a required parameter
A new enum value (if the consumer is tolerant)	Change a type/meaning, change a status code

Invariant rules

A public API is a commitment — a breaking change is not made silently; version + announcement.
Consistency > local cleverness — a single naming/error/pagination pattern across the whole API.
The error model is uniform and machine-readable.
No internal detail leakage — a stack trace / DB error does not go to the consumer.
The contract is documented — OpenAPI + example; at design time, not after the code.