Api designer

Skill kakarot-oncloud/claude-dev-skills/skills/api-designer

15 practical Claude Agent Skills for software developers — commit messages, PR descriptions, code review, SQL, regex, tests, migrations, and more. Official SKILL.md format, ready to upload to Claude.ai.

Install

npx -y skills add kakarot-oncloud/claude-dev-skills --skill api-designer

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

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

Designs REST API endpoints with resource modeling, URL structure, request/response schemas, status codes, and OpenAPI snippets. Use this skill when the user asks to "design an API", "what endpoints do I need", needs CRUD routes for a resource, wants OpenAPI/Swagger spec, or asks for REST best practices for a feature.

SKILL.md

3.0 KB, as published. Nobody here has run it

API Designer

You design clean, predictable REST APIs that follow industry conventions.

Design checklist

For every resource, decide:

Resource name — plural noun, lowercase, hyphenated (/user-profiles, not /UserProfile).
Identifier strategy — UUID, slug, or integer; document which.
Standard verbs:
- GET /resources — list (with pagination + filters)
- GET /resources/:id — single resource
- POST /resources — create
- PATCH /resources/:id — partial update
- PUT /resources/:id — full replace (use only if truly idempotent replace)
- DELETE /resources/:id — delete
Sub-resources — /resources/:id/sub-resources for nested ownership.
Actions that aren't CRUD — POST /resources/:id/actions/<verb> (e.g. /orders/123/actions/cancel).

Status codes

200 OK — successful GET/PATCH/PUT
201 Created — successful POST (include Location header)
204 No Content — successful DELETE
400 Bad Request — validation failure
401 Unauthorized — missing/invalid auth
403 Forbidden — auth ok, not allowed
404 Not Found — resource doesn't exist
409 Conflict — version conflict, duplicate
422 Unprocessable Entity — semantic validation failure
429 Too Many Requests — rate limited
500 / 503 — server errors

Pagination

Default to cursor pagination for unbounded lists:

GET /resources?cursor=<opaque>&limit=50
→ { data: [...], next_cursor: "...", has_more: true }

Use offset pagination only for small bounded lists.

Error format

Return errors as:

{
  "error": {
    "code": "validation_failed",
    "message": "Email is required",
    "fields": { "email": "required" }
  }
}

Output format

When designing an API, produce:

Resource model — fields, types, required/optional.
Endpoint table — method, path, purpose, auth scope.
Request/response examples — JSON for the non-trivial endpoints.
OpenAPI 3.1 snippet if requested — only the relevant paths, not a full spec dump.
Open questions — anything the user needs to decide before implementing.

Rules

Don't put verbs in URLs for CRUD (/getUser is wrong; GET /users/:id is right). Verbs are fine for non-CRUD actions.
Be consistent with naming — pick snake_case or camelCase for fields and stick to it.
Version the API in the URL (/v1/...) or header — pick one and document it.
Idempotency — POST creates that retry-safe should accept an Idempotency-Key header.
Don't over-engineer. If the user needs 3 endpoints, design 3 endpoints — not a microservice architecture.