Rest api design

Skill openagentskills/betterskills/skills/engineering/rest-api-design

Portable, open catalogue of agent skills for Cursor, Claude Code, Windsurf, Copilot, and other AI coding assistants.

Install

npx -y skills add openagentskills/betterskills --skill rest-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

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 or reviews REST HTTP APIs for consistency, versioning, errors, and pagination. Use when defining endpoints, OpenAPI specs, API contracts, or when the user asks about REST resource naming and status codes.

SKILL.md

2.0 KB, as published. Nobody here has run it

REST API Design

Resource naming

Nouns, plural collections: /users, /users/{id}/orders
Actions as sub-resources when not CRUD: /users/{id}/activate (prefer state change via PATCH)
Kebab-case paths; lowercase

HTTP methods

Method	Idempotent	Safe	Typical use
GET	Yes	Yes	Read
POST	No	No	Create, non-idempotent actions
PUT	Yes	No	Full replace
PATCH	No*	No	Partial update
DELETE	Yes	No	Remove

Status codes (defaults)

Code	When
200	Success with body
201	Created (+ `Location` header)
204	Success, no body
400	Client validation error
401	Not authenticated
403	Authenticated, not allowed
404	Resource not found
409	Conflict (duplicate, state)
422	Semantic validation (optional)
429	Rate limited
500	Server error (no internal details)

Error body (consistent shape)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable summary",
    "details": [{ "field": "email", "issue": "invalid format" }]
  }
}

Pagination

Prefer cursor-based for large sets:

{
  "data": [],
  "next_cursor": "opaque-token",
  "has_more": true
}

Offset acceptable for admin or small tables; document limits (limit max 100).

Versioning

URL prefix (/v1/) or header (Accept: application/vnd.company.v1+json)
Never break clients without a new version or deprecation window

Review checklist

Consistent naming and pluralization
Correct status codes (not 200 for errors)
Filtering/sorting documented
Auth on every mutating route
Idempotency keys for POST payments/bookings where needed