Core Concepts

Zwaggen has a small vocabulary. Once you've got these four words, every feature page makes sense.

The four pieces

• Spec — a single .zwaggen.json file. The source of truth. Versioned in git.
• Types — reusable shapes: strings, numbers, objects, arrays, unions, refs to other types.
• Endpoints — HTTP operations (GET /todos, POST /orders, …). Each references types for its params, request body, and responses.
• Environments — named value sets: dev, staging, prod. Each holds a base URL, auth preset, and any variables referenced in a request (e.g. {{env.apiKey}}).

Spec

The spec is the root object. It holds every Type, Endpoint, and Environment. The JSON shape is documented in docs/rules/spec-versioning.md in the repo; the current on-disk schemaVersion is 1.

You never hand-edit this file in practice — the UI owns it. But because it's JSON, it diffs cleanly in git, which is what makes Spec Diff and pull-request review useful.

Types

Types live in a flat namespace keyed by name. You can:

• define a scalar (string, number, integer, boolean, null, literal),
• define a composite (array, object, union),
• or reference another type by name (ref).

Types are the glue. A change to Todo instantly changes every endpoint that returns it. See Type Builder.

Endpoints

An endpoint is a method + path plus:

• path / query / header params (each a ParamDef with a type),
• an optional request body (any type),
• one or more response shapes keyed by status,
• an auth preset (none, bearer, basic, or API key),
• optional tags (grouping in the sidebar),
• optional assertions (see Assertions & Chaining).

See Endpoints.

Environments

An environment holds the per-deployment bits:

• Base URL (overrides the spec-level base URL).
• Auth preset (bearer token, basic creds, API key header/query).
• Variables — key/value pairs you reference as {{env.name}} in paths, headers, or bodies.

Switch environments from the top bar. The Run panel always uses the active environment.

How a run works

When you hit Send in the Run panel, Zwaggen:

1. Resolves {{env.*}} placeholders (including any values written by a previous capture) in the path, headers, and body.
2. Applies the environment's auth preset.
3. Sends the request (via the browser, or via zwaggen-proxy if configured).
4. Validates the response body against the response type for the status code it got back.
5. Records the run in History.
6. Evaluates any assertions and marks the run pass/fail.