Recipe: build a verifiable Worker JSON API

Produce a first edge API with a minimal file tree and explicit success and error responses.

RECIPE · SHIPPABLE OUTCOMEAbout 25 minutesWorker · no external dependencies

Outcome preview

GET /api/health returns JSON with a request ID; every other path returns a structured 404. You will verify both branches.

What you need

Complete deploy your first Worker.
Make sure the local project can run wrangler dev.

File tree

package.json

wrangler.jsonc

index.ts

Implement and verify

src/index.ts

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const requestId = crypto.randomUUID();

    if (request.method === 'GET' && url.pathname === '/api/health') {
      return Response.json(
        { ok: true, requestId },
        { headers: { 'cache-control': 'no-store' } },
      );
    }

    return Response.json(
      { ok: false, error: 'not_found', requestId },
      { status: 404 },
    );
  },
};

Why the health response is not cached

This recipe uses cache-control: no-store to state that health data should be generated live. A later static-content recipe will make a different choice.

AI review prompt

AI workbenchHuman reviewed

Review the API; do not rewrite it

Review the Cloudflare Worker fetch handler below. Report only reproducible issues and check:
- status, JSON, and cache-control for GET /api/health;
- a stable structured 404 for unknown paths;
- leakage of secrets, internal errors, or user input;
- current ES Modules fetch-handler syntax.
Give verification commands before the smallest fix. Do not invent Wrangler fields.

Checkpoint and pitfalls

Every response should contain a new requestId.
A 404 is an expected branch, not a Worker crash.
Do not put API tokens, account IDs, or secrets in responses or the repository.
Before deployment, read the current wrangler deploy documentation and validate in your own preview environment.

Next: understand the API architecture boundary.