skip to content

Admin Control Surface

3 roadmaps5 questions

The server's own HTTP control API: create, list, edit and delete stubs at run time from any language. It separates a live-programmable server from one you can only configure at start-up.

on this pageshow

explore

questions

5

In WireMock, what do GET, POST and DELETE on /__admin/mappings each do?

level: juniorimportance: must knowfreq 70%

answer

  1. the server configures itself over HTTP
  2. everything under one admin prefix
  3. collection resource for stub mappings
  4. POST one, GET the list, DELETE all
  5. WireMock: /__admin/mappings

basics

~20 s

WireMock's admin API at /__admin/mappings lists every registered stub on GET and registers one new stub from the posted body on POST. DELETE on the same path removes all of them. Any HTTP client can drive it while the server runs.

solid answer

~50 s

WireMock serves a control API for itself under the `/__admin` prefix, on the same port as the stubbed responses, so a running server stays programmable over plain HTTP. `GET /__admin/mappings` returns the stub mappings registered right now, each with the id WireMock holds it under. A `POST` to WireMock's `/__admin/mappings` registers one new mapping from the JSON body and returns it with that id — the handle you later use for `GET`, `PUT` or `DELETE /__admin/mappings/{id}`. `DELETE` on WireMock's `/__admin/mappings` is the blunt one: it clears every registered mapping in a single call, including any a neighbouring fixture put there. Because these are ordinary HTTP calls rather than a Java-only API, a Node or Python suite can stub a lighthouse maintenance API with nothing but an HTTP client, and a `curl` on the collection is a complete answer to *what is this server configured to do*.

go deeper

for a junior

Be ready to name the path — /__admin/mappings — and say what GET, POST and DELETE do on it. The point of the question is that WireMock is configurable while it is running, not only when it starts.

for a middle

Explain that POST returns the mapping with the id WireMock assigned, and that this id is what every single-mapping call afterwards addresses. Say precisely what DELETE on the collection clears and what it leaves alone.

for a senior

Show that you treat the admin API as a control plane you own: register from the case, capture ids, and remove exactly what you registered, so one fixture's stubs never quietly decide another fixture's result.

for a principal

Own the team rule for how suites drive stub servers — programmed over /__admin at run time versus a fixed set nobody edits — and be able to argue the cost of each in reviewability, reproducibility and debugging time.

## The two kinds of traffic a WireMock server answers A running WireMock server answers two quite different kinds of request on the same port. The first is the traffic your code under test sends — a `GET /lighthouses/BEACHY-HEAD/lamp` aimed at what the code believes is the lighthouse maintenance API — and WireMock answers it from whichever stub mapping matches. The second is traffic aimed at WireMock **itself**, and all of it lives under the `/__admin` prefix. That second surface is the admin API: an ordinary HTTP API whose resources are the server's own configuration rather than the fake upstream's data. WireMock's `/__admin/mappings` is the collection resource for the stub mappings that server currently holds. The three calls in the question are the collection-level operations on it, and together they are the minimum you need to drive a stub server from outside the process that started it. The consequence people miss is that a WireMock server is **programmable**, not merely configured. A stub server that only reads its mappings when it boots forces a restart for every change. A server with a live control API lets a test add a stub, run one case against it, and take it away again while the process stays up. ## WireMock's `GET /__admin/mappings` — read the registered set A GET on the collection returns the stub mappings the server holds right now, each carrying the id WireMock stores it under. Two things follow: - A test or a human can **discover** what is loaded instead of assuming it. If a lighthouse suite fails because the lamp endpoint answered something unexpected, the first diagnostic is to read the set back and see what the server thought it should answer. - The document it returns is the export half of a round trip. WireMock's `POST /__admin/mappings/import` accepts a document of that same shape, so what you read out can be fed back in. ## WireMock's `POST /__admin/mappings` — register one stub at run time A POST to the collection registers exactly **one** new mapping from the JSON body you send, and returns that mapping with the id WireMock assigned it. That id is the handle for everything single-mapping that follows: - In WireMock, `GET /__admin/mappings/{id}` reads that one mapping back. - In WireMock, `PUT /__admin/mappings/{id}` replaces that one mapping. - In WireMock, `DELETE /__admin/mappings/{id}` removes that one mapping and leaves the rest registered. A case that keeps the id can clean up precisely after itself. A case that throws the id away has only the blunt instrument left. What goes *inside* the posted body — which matchers select the request, what the canned reply contains — is a subject of its own; the admin API's job here is carriage. It takes the definition, stores it, and hands you back a way to address it. ## WireMock's `DELETE /__admin/mappings` — clear the whole set A DELETE on the collection removes every registered mapping in one call. It is the right tool when a fixture owns the server outright and wants a clean slate, and the wrong tool when a single stale stub is the problem, because it also destroys whatever a neighbouring fixture registered. Blurring the collection call with the `{id}` call is the commonest mistake on this surface. | WireMock admin call | effect | |---|---| | `GET /__admin/mappings` | list the mappings registered right now | | `POST /__admin/mappings` | register one mapping, get its id back | | `DELETE /__admin/mappings` | remove every registered mapping | | `GET /__admin/mappings/{id}` | read one mapping back | | `PUT /__admin/mappings/{id}` | replace that one mapping | | `DELETE /__admin/mappings/{id}` | remove that one mapping | | `POST /__admin/mappings/import` | load a document of many mappings | ## Why "it is plain HTTP" is the whole point The admin API is not a Java API with an HTTP transport bolted on; it is an HTTP API that WireMock's own Java DSL happens to call. Being able to state the consequences is what separates a candidate who has used the tool from one who has only read about it: 1. **Language independence.** A Node, Python, Go or Kotlin suite can register a lighthouse stub with nothing but an HTTP client, and no client library can do anything over the wire that `curl` cannot. 2. **Inspectability.** A `curl` on WireMock's `/__admin/mappings` is a complete debugging session for "what is this server configured to do right now". 3. **Change without restart.** Stubs can be added between two steps of one scenario, so the fake upstream can be reconfigured mid-test. 4. **Symmetry.** Everything you register you can read back, address by id and remove — which is what makes precise per-case cleanup possible at all. By contrast, MockServer exposes its own control plane under a different prefix entirely and registers stubs with `PUT /mockserver/expectation`, so admin knowledge does not transfer between the two by guessing. ## Where this surface stops WireMock's `/__admin` prefix carries far more than mappings. The requests the server received, scenario state, recording control, files and settings each have their own resources under the same prefix, and each is a separate subject with its own rules. For this question the boundary is simple: in WireMock, `/__admin/mappings` is where stub definitions live, it is addressable while the server runs, and GET, POST and DELETE on the collection read the set, add one to it and empty it.

  • How does a test discover the id of a mapping it registered a moment ago?
    It reads the id from the response to `POST /__admin/mappings`, which returns the stored mapping with the id WireMock assigned. If the id was thrown away, `GET /__admin/mappings` lists the registered set and every entry carries its id, so the mapping can be found again by the definition you recognise. Capturing the id at registration is the cheap option; searching the collection afterwards is the recovery.
  • Does WireMock's admin API listen on a different port from the stubbed responses?
    No — `/__admin` is served on the same port as the stubbed traffic, which is why that prefix is reserved and a stub cannot claim a path underneath it. One consequence worth saying out loud: anything that can reach the fake upstream can also reconfigure it, so the admin API is a control plane and should be treated as one.
  • Why would a suite register stubs over the admin API rather than ship one fixed set?
    Because the stub a case needs often depends on the case: one wants the lighthouse lamp endpoint healthy, the next wants it answering 503 for the same station. Registering from the test keeps the assumed upstream behaviour beside the assertion that depends on it, and `DELETE /__admin/mappings/{id}` lets the case remove exactly what it added.

saying these in an interview costs you the question

  • Says WireMock must be restarted to add a stub
  • Thinks only the Java client can register mappings
  • Confuses DELETE /__admin/mappings with deleting one stub
  • Cannot name the path stub mappings are registered on
  • Assumes the admin API needs its own separate port
open as a page

In WireMock, how do you remove one run-time stub without clearing every other mapping?

level: middleimportance: must knowfreq 62%

basics

~20 s

Call DELETE /__admin/mappings/{id} with the id WireMock returned when the stub was registered. That removes exactly that mapping and leaves the rest in place, while DELETE on the collection path clears every registered mapping at once.

open as a page

In WireMock, what does POST /__admin/mappings/import do that POST /__admin/mappings does not?

level: middleimportance: should knowfreq 52%

basics

~20 s

WireMock's POST /__admin/mappings registers one stub mapping per call and hands it back with its id. WireMock's POST /__admin/mappings/import takes a document holding many mappings and loads the whole batch in a single call, adding to what is already registered.

open as a page

In WireMock, why can PUT /__admin/mappings/{id} lose parts of the stub you meant to keep?

level: seniorimportance: should knowfreq 48%

basics

~20 s

WireMock stores what you send to PUT /__admin/mappings/{id} as the whole mapping under that id. It is a replacement, not a patch, so any matcher missing from your body is gone. Read the mapping first, then put it back complete.

open as a page

Which call adds a stub to a running Mountebank imposter, and what does WireMock use instead?

level: middleimportance: nice to knowfreq 40%

basics

~20 s

In Mountebank, POST /imposters/:port/stubs adds one stub to an imposter that is already listening, and PUT on that path replaces its whole stub list. WireMock has no imposter object: it registers mappings with POST /__admin/mappings.

open as a page