agentsclimarketplace

Api design

Skill pixelcrafts-app/agent-skills/plugins/api-standards/skills/api-design

REST API design principles — resource naming, HTTP semantics, status codes, pagination, errors, auth, rate limiting, versioning. Framework-agnostic.From its SKILL.md

Install
npx -y skills add pixelcrafts-app/agent-skills --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

  • 1 stars1 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.

SKILL.md

3.2 KB, as published. Nobody here has run it

API Design

Design REST APIs that are predictable, evolvable, and safe. Principles are firm; the numbers and snippets below are starting points — fit them to the project.

Principles (firm)

  1. URLs are plural, kebab-case nouns. No verbs in paths. /users/:id, /users/:id/orders. Verbs only for non-CRUD actions (/orders/:id/cancel).
  2. HTTP method = semantics. GET safe, PUT/DELETE idempotent, POST not. Don't return 200 {success:false} — use the real status.
  3. Errors are typed. Body: { error: { code, message, details? } }. The client switches on code, not status alone. Never leak stack traces or SQL.
  4. List endpoints paginate. Always bounded; never return unbounded sets.
  5. Validate every inbound payload at the boundary (Zod / class-validator / Pydantic). Reject 422 on semantic failure, 400 on malformed.
  6. Authn + authz on every endpoint — or mark it explicitly public. Ownership-check resources (a user reads only their own).
  7. Version only on breaking change. Add fields freely; rename/remove/retype → new version.

Reference (adjust to context)

Status codes: 200/201/204 success · 400/401/403/404/409/422/429 client · 500/502/503 server (send Retry-After on 503/429).

Pagination — pick per use case:

NeedUse
Jump to page N, small/admin datasetsOffset
Feeds, infinite scroll, large/concurrent data, public APIsCursor

Filtering/sorting: query params — ?status=active&sort=-created_at&fields=id,name.

Auth: user sessions → Authorization: Bearer <token>; service-to-service → API key header. No custom session headers (invisible to gateways/scanners).

Rate limiting: tier by caller, stricter on auth endpoints, return X-RateLimit-* + Retry-After. Example tiers: anon 30/min, authed 100/min, premium 1000/min — set real values from traffic, don't copy these.

Auth contract (any stack, when the API issues tokens)

  • Two checks per protected route: authentication (token valid) AND authorization (identity allowed this resource). A valid token is not permission; never merge them into one guard.
  • Refresh rotation: each refresh issues new access + refresh tokens and invalidates the old refresh immediately. Reuse of an invalidated token → revoke the whole family, force re-login.
  • Logout revokes server-side (denylist or family rotation) — clearing the client cookie leaves the token alive.
  • Expiry bounds: access ≤ 15 min; refresh has an explicit absolute max (7–30 days) plus inactivity expiry. "Never expires" is invalid.
  • OAuth code flow uses PKCE: random code_verifier ≥ 43 chars, only its SHA-256 challenge in the authorize request, verifier only in the token exchange, never stored after.
  • No user enumeration: "user not found" and "wrong password" return the identical response. Log server-side with context; never expose stack traces or internal IDs.
  • Rate-limit login, refresh, and password reset — absence is a security gap, not a missing feature.

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.