unkn0wn-root/resterm v0.47.1 on GitHub

Mock APIs, directly from your Resterm files

This release lets Resterm serve responses from the same .http/.rest files you already use for real requests, from either the CLI or the TUI.

This version focuses on HTTP mocking. Native gRPC and GraphQL-aware mocking are planned for future releases.

Start with one response

A mock is a route followed by an ordinary raw HTTP response:

### Create user
# @mock method=POST path=/users/{id} default=true latency=100ms
HTTP/1.1 201 Created
Content-Type: application/json
X-Request-ID: {{$uuid}}

{
  "id": {{json.path.id}},
  "name": {{json.body.user.name}},
  "view": {{json.query.view}}
}

Start it in one terminal:

resterm mock ./api.http

Then call it from another:

curl --request POST \
  'http://127.0.0.1:8080/users/alice?view=full' \
  --header 'Content-Type: application/json' \
  --data '{"user":{"name":"Ada"}}'

The response uses values from the route, query string, and request body:

{
  "id": "alice",
  "name": "Ada",
  "view": "full"
}

Interpolation works in response headers and both inline and file-backed bodies. Plain placeholders such as {{path.id}} insert text directly. Inside JSON, use the json. prefix so Resterm emits a complete JSON value with the required quoting and escaping. JSON body values also retain their original type and numeric precision.

Routes can have named or default scenarios, fixed latency, wildcard paths, and @match conditions based on query parameters, headers, or a recursive subset of the JSON request body. A scenario can also be selected explicitly with X-Resterm-Mock.

Model APIs that change over time

Response sequences make polling, retries, and eventually consistent APIs straightforward:

### Poll payment
# @mock method=GET path=/payments/{id} sequence=polling
HTTP/1.1 503 Service Unavailable
Retry-After: 1
Content-Type: application/json

{"id": {{json.path.id}}, "status": "pending"}
---
HTTP/1.1 200 OK
Content-Type: application/json

{"id": {{json.path.id}}, "status": "completed"}

In this example the first call returns 503, the second returns 200 and later calls continue returning the final response.

Send X-Resterm-Mock-Status: 200 to pin the completed response without advancing the sequence. Request logs show progress such as polling 1/2.

Sequence state belongs to the scenario, so it is shared by all clients and concrete wildcard values. Editing a source or fixture resets sequences as part of the next successful reload.

Built into the Resterm workflow

resterm mock serves one request file or an entire workspace, with recursive discovery, configurable addresses, CORS controls, request logs and source and fixture watching.
Reloads are atomic. An invalid edit is reported while the last valid route set keeps serving.
In the TUI, g Shift+M starts or stops the workspace server and :mock logs opens its request log.
Press g a to capture the focused HTTP response as a new mock block. Captures remain unsaved so headers and bodies can be checked for credentials or personal data first.
OpenAPI imports can generate mock blocks with --openapi-mode mocks, or requests and mocks together with --openapi-mode both.
Loopback servers get convenient browser CORS defaults. Public binds disable automatic CORS and print an exposure warning unless explicitly configured.

Bring your own TLS

The CLI mock server remains HTTP by default, but it can serve HTTPS using your own PEM certificate and private key:

mkcert -install
mkcert 127.0.0.1 localhost

resterm mock \
  --tls-cert ./127.0.0.1+1.pem \
  --tls-key ./127.0.0.1+1-key.pem \
  ./requests

Note: Both TLS flags are required.

Resterm does not generate certificates. For explicit Resterm client trust with mkcert, copy the public rootCA.pem from the directory printed by mkcert -CAROOT next to the request file and add # @setting http-root-cas ./rootCA.pem.