Skip to content

The mock’s own endpoints are at /__mock, beside the APIs. With an X-Mock-Session header, each works on that session’s data only.

Endpoint What it does
GET /__mock/health Ready check: 200 with the APIs served. Works without --stateful too.
GET /__mock/model What the mock made of each spec: resources, and every operation with its label. /<api id> for one API. Each resource has records, how many the caller’s session holds now, and seeded, how many a reset goes back to.
GET /__mock/model/<api id>/resources/<Resource> One resource: fields, how each is seeded, links, operations. A resource whose schema is one of several objects (a oneOf or anyOf with no fields of its own) has shape: { kind, options, by }, the schema names of its shapes and the property that tells them apart; its fields are all of theirs, and a field only some have lists them in onlyIn. A schema with no fields at all has shape: { kind: "none" }. A field that holds an object, or a list of objects, has its own fields, three levels deep at most; under a field that copies another resource’s records they have no seededAs. Add /sample for a generated record that is not stored (?seed= to repeat it).
GET /__mock/model/<api id>/operations/<id> One operation: what the mock does, its parameters, request, responses and a sample response. Each response says where its body comes from (body: example, examples with their names, or generated) and, with returned: true, which one a request gets unless Prefer: code= asks for another. ?code=404 makes the sample that response’s. A query parameter the mock had to assume something about has review (what it assumed: “matches no field of `Article`”), and the operation then has review: { parameters, other }: how many parameters, and the rest of its review note. <id> is the id the model lists, URL-encoded.
GET /__mock/lint/<api id> What lint finds in the API’s spec, as rapidoc lint --stateful reports it: every finding with its rule and line, and the share of checks that passed per category. The first call lints the spec, which takes a few seconds on a large one; the answer is kept.
GET /__mock/settings How the mock was started: state, seed, rows, delay, tokens, the APIs.
PATCH /__mock/settings Changes the response delay while the mock runs: { "delay": 250 }.
POST /__mock/apis Adds a spec while the mock runs: { "url": "https://example.com/openapi.yaml" }, or { "text": "<YAML or JSON>", "name": "orders-api.yaml" }. It is served at once under an id made from its file name (pasted text without a name: its title), made unique, with state, until the mock stops. Answers 201 with { id, title, operations, stateful }, or 400 saying why the spec can’t be served. Accepted only from the machine the mock runs on (403 otherwise): it makes the mock read the address you give, and a $ref in the text can name a local file. GET /__mock/settings lists such an API with imported: true.
DELETE /__mock/apis/<api id> Removes an API added with POST /__mock/apis. The APIs the mock started with can’t be removed.
POST /__mock/reset Puts the data back to what the mock started with. ?api=<id> resets one API. With a body { "rows": 25, "seed": 7 } it makes new seed data of that size, and drops every session’s records.
GET /__mock/state The stored records. Narrow it with /<api id>, /<api id>/<Resource> or /<api id>/<Resource>/<key>.
POST /__mock/snapshot Returns all stored records as one JSON document. ?api=<id> for one API.
POST /__mock/restore Replaces the records with the document you send: a snapshot, or data your test wrote.
GET /__mock/ui The Mock UI.

The sentences the model writes (does, why, review, a parameter’s role) put the names they take from the spec, a resource, a parameter or a field, in backticks: “Lists the stored `Owner` records, filtered by `lastName`.” The Mock UI shows them as code; rapidoc lint --stateful prints the same notes without the marks.

snapshot returns it and restore takes it:

{ "<api id>": { "<Resource>": [ { "id": 1, "name": "Biscuit" } ] } }
  • A restore replaces every resource of the APIs it names; a resource it leaves out becomes empty. Other APIs are left alone.
  • A document that is wrong changes nothing.
  • A record that lives under a parent without having a field for it carries the parent in $parents. Keep that entry when you restore.

Problems come back as application/problem+json, with a detail that says what to do. Without --stateful, every endpoint except health returns 409.

These endpoints are open to any caller: anyone who can reach the mock can reset or replace its data. The mock is a development tool. Don’t expose it publicly.

An OpenAPI description of this API, shown here as an interactive reference, is planned.