api-design

Files (2)

• SKILL.md
• SKILL.md.lock

SKILL.md (first lines)

<!-- bodyRef: skills/sources/api-design.md -->

<!-- Generated by `harness skills bootstrap`. Edit to tune; re-run to regenerate. -->
<!-- Static skills point at live docs by design — do not hardwire version-pinned API here. -->

Use this skill when designing or reviewing an HTTP/RPC API surface.

## Concepts (timeless)
- Resources are nouns; the method carries the verb; the status code carries the outcome.
- Model collections and items consistently; paginate every unbounded list (cursor beats offset at scale).
- Keep a stable error envelope; version at the boundary, not per field.
- Make writes idempotent where a client may retry; document idempotency keys.
- Authn/authz and rate-limiting belong on every public route, not as an afterthought.

## Pull current docs first
Do NOT rely on memorized signatures — APIs and framework conventions change.
Before writing handlers, fetch the CURRENT docs for THIS project's stack:
- HTTP semantics: https://developer.mozilla.org/docs/Web/HTTP
- your web framework's current routing + validation guide

## Checklist
- [ ] Resource URLs are nouns, hierarchical, consistently pluralized
- [ ] Correct status codes (201/204; 4xx vs 5xx); errors use one envelope
- [ ] Pagination, filtering, sorting documented for collections
- [ ] Authn + authz + rate-limit on every public route
- [ ] Backwards-compatible changes; breaking changes are versioned

## Gotchas

_Highest-signal section. Seed empty; grow it from real failures this skill
hits — `harness skills propose` suggests entries here from drift evidence._

- _none observed yet_

From ichiorca/shipsignal, Apache-2.0.

More from ichiorca/shipsignal