theme-rest-api

name	theme-rest_api
description	REST API (headless, no UI) palette: variants, resources, entities, and flows for building a varied API. Use when theme_preset is rest_api.

REST API theme

Domain

A headless JSON API with no UI (deployment is API-only). Discovery happens through the API surface itself — an OpenAPI/Swagger doc, a /api index, or predictable resource routes. Authorization on each verb and ownership of resources are the whole game here.

Note for the planner/skeleton: there are no pages and no UI. There is no frontend framework. Always surface a discoverable API description (GET /api, /openapi.json, or /docs) so the lab is explorable.

Application variants — pick ONE per lab

Honor any hint in theme_free_text / custom_prompt; otherwise pick one.

• Generic CRUD service — items / orders / users resources.
• IoT device fleet — devices, telemetry, commands, firmware.
• Payments API — merchants, charges, refunds, webhooks.
• Content feed API — articles, authors, feeds, subscriptions.
• Internal microservice — one bounded domain consumed by other services.
• Geolocation / maps API — places, geocoding, routes, saved locations.
• Notification / webhook service — message sends, delivery status, subscriptions, retries.

Roles — choose the set that fits the variant

• anon — only the API description / health, or nothing.
• user (API key / bearer token) — operate on own resources.
• service — machine-to-machine token with broader scope.
• admin — privileged scope across all resources.

Most exploits run as user (or a low-scope token). Auth is header-based (Authorization: Bearer … / X-API-Key), not a cookie session.

Candidate resource collections — select a coherent subset

Instead of pages, expose a coherent set of resources, each with the standard verbs. Size the subset to endpoint_count. Candidates (variant-dependent): /api/v1/users, /api/v1/items, /api/v1/orders, /api/v1/devices, /api/v1/devices/{id}/telemetry, /api/v1/devices/{id}/commands, /api/v1/charges, /api/v1/refunds, /api/v1/merchants, /api/v1/articles, /api/v1/feeds, /api/v1/subscriptions, /api/v1/webhooks, plus GET /api (index) and GET /openapi.json (schema).

Candidate entities (seed tables) — select what the variant needs

Core (most variants):

• users — id, email?, role, created_at
• api_keys — id, owner_id, key_hash, scope, last_used_at
• items (generic) — id, owner_id, name, sku, qty, ...domain fields
• orders (generic) — id, owner_id, item_id, qty, status, total_cents

IoT device fleet (variant):

• devices — id, owner_id, name, status, firmware_version, last_seen
• telemetry — id, device_id, metric, value, ts
• commands — id, device_id, type, payload, status, issued_by
• firmware — id, version, artifact_path?, signed?

Payments API (variant):

• merchants — id, owner_id, name, api_mode (test/live)
• charges — id, merchant_id, amount_cents, currency, status, customer_ref
• refunds — id, charge_id, amount_cents, status, reason
• webhooks — id, merchant_id, target_url, events, secret

Content feed API (variant):

• authors — id, user_id, display_name
• articles — id, author_id, title, body, visibility, published_at
• feeds — id, owner_id, name, query/filter
• subscriptions — id, user_id, feed_id, status

Internal microservice (variant):

• <domain_entity> — id, owner_id/tenant_id, ...bounded-domain fields
• events / audit — id, actor_id, action, target_id, ts

Seed resources owned by ≥2 different principals (and ≥2 tenants where relevant) so cross-owner / cross-tenant access is testable.

Candidate flows — select the ones matching chosen resources

(All start after whatever auth the spec specifies.)

1. List own resources → fetch one by id → confirm ownership scoping.
2. Create a resource → update it → delete it.
3. Filter / search / sort a collection with query params.
4. Paginate a large collection (?page=&limit=) and follow next links.
5. Fetch the API description (GET /api / /openapi.json) → discover routes.
6. (IoT) Register a device → post telemetry → send a command → poll status.
7. (IoT) Push a firmware version → devices report updated firmware_version.
8. (payments) Create a charge → issue a partial/full refund → receive a webhook.
9. (payments) Register a webhook endpoint → server delivers a signed callback.
10. (content) Publish an article → it appears in a subscribed feed → unsubscribe.

Candidate endpoints — a feature may span several

Endpoints are a shared surface, not owned 1:1 by a feature (a single feature often spans several, and an endpoint can back multiple features). Pick a coherent subset alongside the resource collections above. Grouped by resource:

• discovery — GET /api, GET /openapi.json, GET /docs, GET /health
• users — GET /api/v1/users, GET/PUT /api/v1/users/{id}, GET /api/v1/users/me
• api keys — GET/POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id}
• items / orders (generic) — GET/POST /api/v1/items, GET/PUT/DELETE /api/v1/items/{id}, GET/POST /api/v1/orders, GET /api/v1/orders/{id}
• devices (IoT) — GET/POST /api/v1/devices, GET/PUT/DELETE /api/v1/devices/{id}, GET/POST /api/v1/devices/{id}/telemetry, POST /api/v1/devices/{id}/commands
• firmware (IoT) — GET/POST /api/v1/firmware, POST /api/v1/devices/{id}/firmware
• charges / refunds (payments) — GET/POST /api/v1/charges, GET /api/v1/charges/{id}, POST /api/v1/charges/{id}/refunds, GET /api/v1/refunds/{id}
• webhooks (payments) — GET/POST /api/v1/webhooks, DELETE /api/v1/webhooks/{id}
• articles / feeds (content) — GET/POST /api/v1/articles, GET/PUT/DELETE /api/v1/articles/{id}, GET /api/v1/feeds/{id}, GET/POST /api/v1/subscriptions
• admin — GET /api/v1/admin/{resource}, POST /api/v1/admin/{resource}/{id}/...

Where vulnerabilities fit naturally

• idor → GET /api/v1/{resource}/{id} returning another principal's resource (no owner check).
• auth_bypass → a verb missing the authz check that its siblings enforce (e.g. GET protected but DELETE not).
• sqli → filter / sort / q query params interpolated into SQL.
• business_logic / mass-assignment → POST/PUT body accepting privileged fields (role, owner_id, amount, status, scope).
• ssrf → a webhook / firmware / callback URL the server fetches.
• privilege_escalation → low-scope token reaching /api/v1/admin/....

Diversity guidance

Pick ONE variant and a coherent subset of resources — a payments API and an IoT fleet diverge sharply. Size the resource set to endpoint_count; let theme_free_text / custom_prompt bias the variant and naming. Keep it headless: no pages, no frontend, but always a discoverable API description.