REST resource conventions
Agent rules for naming and shaping HTTP resources (plural nouns, methods and status codes, one resource shape, cursor pagination, versioning), independent of framework and layout, plus an AGENTS.md section recording the project's choices.
Category: tooling
In your existing repository
Ask your agent to check compatibility, follow this fragment’s brief, and verify the resulting project. What happens next
- Applies to:
- api
Add to your project
Paste the prompt into the coding agent working on your project.
View prompt
Or use the terminal
npx @steamfield/stacks add rest-api| Step | Phase | Layer | Command |
|---|
No additional verify steps declared. Run the project’s existing verification after applying the brief.
Use with a new stack
Starting fresh instead? These stacks support this fragment.
- astro-fullstackdefault
npx @steamfield/stacks new astro-fullstack - mobile-expooptional
npx @steamfield/stacks new mobile-expo --with rest-api - python-apioptional
npx @steamfield/stacks new python-api --with rest-api - go-apidefault
npx @steamfield/stacks new go-api - python-reactoptional
npx @steamfield/stacks new python-react --with rest-api - typescript-apidefault
npx @steamfield/stacks new typescript-api
Alternatives in tooling
- Effect Schema
Effect Schema as the one validation and typing layer for data crossing a trust boundary (requests, config, storage, third-party and LLM output), with branded ids, tagged errors, JSON Schema for tools, and round-trip plus property tests.
Also applies to: astro-fullstack, mobile-expo, python-react, typescript-api
- Effect testing and API skill
Effect testing with @effect/vitest (fresh real layers per test, TestClock instead of sleeps, typed failure and defect assertions), shipped Effect guidance for each agent, and an agent skill written from the installed Effect release's declarations.
Also applies to: astro-fullstack, mobile-expo, python-react, typescript-api
- Git hooks (lefthook)
lefthook git hooks that format and lint staged files, enforce Conventional Commits, and run the project's tests before push.
Also applies to: astro-fullstack, mobile-expo, python-api, go-api, python-react, typescript-api
- OpenTelemetry (OTLP) for Effect servers
OpenTelemetry traces, logs and metrics over OTLP for the Effect server in typescript-api, astro-fullstack and react-router. One observability layer adds trace ids to the existing logs, exports nothing without an endpoint, and is tested with an in-memory tracer and a loopback OTLP receiver.
Also applies to: astro-fullstack, typescript-api
- rr remote test runner
Configures rr (github.com/rileyhilliard/rr) so the project's test, lint, and build commands can run on remote machines over SSH, with a committed .rr.yaml of named tasks, an AGENTS.md section, and the rr Claude Code plugin.
Also applies to: astro-fullstack, mobile-expo, python-api, go-api, python-react, typescript-api
Files
- docs/guidance/rest-api/index.md
- docs/guidance/rest-api/rest-api.md
Usage
Among stacks projects in the 28 days through 30 Oct 2026: 13,330 projects; 74% reached a green verify (73–76%, n=2,475).
Weekly projects by stack
Projects whose final fragment set included this fragment, grouped by stack.
- astro-fullstack
- go-api
- python-api
- typescript-api
- astro-fullstack
- go-api
- python-api
- typescript-api
Stacks projects per UTC week through 30 Oct 2026. Published stack counts only.
Data table
| Week ending | Stack | Projects |
|---|---|---|
| 5 Jul 2026 | astro-fullstack | – |
| 12 Jul 2026 | astro-fullstack | – |
| 19 Jul 2026 | astro-fullstack | – |
| 26 Jul 2026 | astro-fullstack | – |
| 2 Aug 2026 | astro-fullstack | 5 |
| 9 Aug 2026 | astro-fullstack | 5 |
| 16 Aug 2026 | astro-fullstack | – |
| 23 Aug 2026 | astro-fullstack | 10 |
| 30 Aug 2026 | astro-fullstack | 5 |
| 6 Sept 2026 | astro-fullstack | 10 |
| 13 Sept 2026 | astro-fullstack | 5 |
| 20 Sept 2026 | astro-fullstack | 5 |
| 27 Sept 2026 | astro-fullstack | 10 |
| 4 Oct 2026 | astro-fullstack | – |
| 11 Oct 2026 | astro-fullstack | 10 |
| 18 Oct 2026 | astro-fullstack | 5 |
| 25 Oct 2026 | astro-fullstack | 5 |
| 5 Jul 2026 | go-api | 165 |
| 12 Jul 2026 | go-api | 280 |
| 19 Jul 2026 | go-api | 415 |
| 26 Jul 2026 | go-api | 485 |
| 2 Aug 2026 | go-api | 560 |
| 9 Aug 2026 | go-api | 555 |
| 16 Aug 2026 | go-api | 635 |
| 23 Aug 2026 | go-api | 635 |
| 30 Aug 2026 | go-api | 685 |
| 6 Sept 2026 | go-api | 745 |
| 13 Sept 2026 | go-api | 780 |
| 20 Sept 2026 | go-api | 835 |
| 27 Sept 2026 | go-api | 845 |
| 4 Oct 2026 | go-api | 910 |
| 11 Oct 2026 | go-api | 950 |
| 18 Oct 2026 | go-api | 1,010 |
| 25 Oct 2026 | go-api | 965 |
| 5 Jul 2026 | python-api | – |
| 12 Jul 2026 | python-api | – |
| 19 Jul 2026 | python-api | – |
| 26 Jul 2026 | python-api | – |
| 2 Aug 2026 | python-api | – |
| 9 Aug 2026 | python-api | – |
| 16 Aug 2026 | python-api | – |
| 23 Aug 2026 | python-api | – |
| 30 Aug 2026 | python-api | – |
| 6 Sept 2026 | python-api | – |
| 13 Sept 2026 | python-api | – |
| 20 Sept 2026 | python-api | – |
| 27 Sept 2026 | python-api | – |
| 4 Oct 2026 | python-api | – |
| 11 Oct 2026 | python-api | – |
| 18 Oct 2026 | python-api | – |
| 25 Oct 2026 | python-api | – |
| 5 Jul 2026 | typescript-api | 470 |
| 12 Jul 2026 | typescript-api | 785 |
| 19 Jul 2026 | typescript-api | 1,010 |
| 26 Jul 2026 | typescript-api | 1,285 |
| 2 Aug 2026 | typescript-api | 1,330 |
| 9 Aug 2026 | typescript-api | 1,605 |
| 16 Aug 2026 | typescript-api | 1,695 |
| 23 Aug 2026 | typescript-api | 1,810 |
| 30 Aug 2026 | typescript-api | 1,920 |
| 6 Sept 2026 | typescript-api | 1,895 |
| 13 Sept 2026 | typescript-api | 2,100 |
| 20 Sept 2026 | typescript-api | 2,170 |
| 27 Sept 2026 | typescript-api | 2,190 |
| 4 Oct 2026 | typescript-api | 2,395 |
| 11 Oct 2026 | typescript-api | 2,605 |
| 18 Oct 2026 | typescript-api | 2,655 |
| 25 Oct 2026 | typescript-api | 2,720 |
By stack
How often this fragment stays in a default composition, or gets attached as an option.
Stacks projects · 28 days through 30 Oct 2026. Counts rounded to 5.
Data table
| Stack | Projects | Role | Share |
|---|---|---|---|
| astro-fullstack | 30 | Default · kept | 81% |
| go-api | 3,605 | Default · kept | 91% |
| python-api | 5 | Optional · attached | 21% |
| typescript-api | 9,690 | Default · kept | 92% |
Green rate with and without it
This compares projects; it isn't an effect of the fragment.
Not enough runs in this breakdown yet.
Stacks projects · 28 days through 30 Oct 2026. Counts rounded to 5.
Often used with
Co-occurrence above the baseline, within a stack. Required fragment pairs are excluded.
Not enough runs in this breakdown yet.
Stacks projects · 28 days through 30 Oct 2026. Counts rounded to 5.
Computed 31 Oct 2026, through 30 Oct 2026. Numbers describe stacks projects, not the ecosystem.