skip to content

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

level: middleimportance: should knowfreq 52%

answer

  1. one call or many calls
  2. batch load over the admin API
  3. the same document the list returns
  4. WireMock: POST /__admin/mappings/import
  5. additive; clearing is a separate DELETE

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.

solid answer

~50 s

Both routes put stub mappings into a running WireMock over the admin API, but they differ in granularity and in what you get back. `POST /__admin/mappings` registers exactly one mapping from the body and returns it with the id WireMock assigned, which is what a test needs if it later means to edit or remove that mapping by id. WireMock's `POST /__admin/mappings/import` takes a document containing many mappings — the same shape `GET /__admin/mappings` hands you when you read the set back — and loads them in one round trip, which is how a suite installs a whole lighthouse maintenance fixture at the start of a run. Import is additive: it registers what the document holds and does not by itself remove anything already there, so clearing is still a separate `DELETE` on WireMock's `/__admin/mappings`. If you need ids for imported mappings, read them back from the collection.

code

json · 16 lines
json
{
  "mappings": [
    {
      "request": { "method": "GET", "url": "/lighthouses/BEACHY-HEAD/lamp" },
      "response": { "status": 200, "jsonBody": { "lampHours": 412 } }
    },
    {
      "request": { "method": "GET", "url": "/lighthouses/PORTLAND-BILL/lamp" },
      "response": { "status": 200, "jsonBody": { "lampHours": 97 } }
    },
    {
      "request": { "method": "GET", "url": "/lighthouses/START-POINT/optic/rotation" },
      "response": { "status": 503, "jsonBody": { "error": "telemetry link down" } }
    }
  ]
}

go deeper

for a junior

Know that both routes add stub mappings to a running WireMock, and that import is the bulk form. Being able to say which one hands you an id back is enough at this level.

for a middle

Explain the round trip: the document import accepts has the same shape the collection GET returns, so a configured set can be copied between servers. Say clearly that import adds rather than replaces.

for a senior

Show judgment about which form a suite should use: ids and precise teardown argue for single POSTs, a large fixture installed once argues for import, and a set that must be exact means clearing first.

for a principal

Decide how mapping sets travel between environments in your organisation — as documents imported over the admin API, or assembled call by call — and be able to defend the choice on reviewability and reproducibility grounds.

## Two ways stubs arrive over the admin API WireMock's admin API gives you two entry points for putting stub mappings into a server that is already running, and the choice between them is about **granularity**, not capability. Both are POSTs, both live under WireMock's `/__admin/mappings`, and both accept the same kind of mapping objects. What differs is how many arrive per call and what the call gives you back to hold on to. Think of the collection resource as a drawer. WireMock's `POST /__admin/mappings` files one index card into it and hands you a receipt with the card's id on it. WireMock's `POST /__admin/mappings/import` hands the whole box over in a single trip. ## WireMock's `POST /__admin/mappings` — one mapping, one receipt The single-mapping POST is the one a test reaches for when the mapping is part of the test's narrative: - It registers exactly one mapping from the JSON body. - It returns that mapping with the id WireMock assigned it. - That id is what WireMock's `GET`, `PUT` and `DELETE /__admin/mappings/{id}` address afterwards. That receipt is the reason to prefer it for anything a case must undo. A case that stubs `GET /lighthouses/BEACHY-HEAD/lamp` to answer 503 for one scenario wants to remove precisely that mapping when it finishes, and the id is how it does so. ## WireMock's `POST /__admin/mappings/import` — the batch The import route takes a document holding **many** mappings and loads them in one call. Its shape is the same one WireMock's `GET /__admin/mappings` produces, which is what makes the pair a genuine round trip: read the registered set out of one server, feed the document into another, and the second server is configured like the first. That matters in three practical ways: 1. **One round trip instead of N.** A lighthouse fixture of forty mappings is one HTTP call rather than forty, which is the difference between a fixture that is instant and one you notice in every run. 2. **The batch is a document you can hold.** Because the payload is a single artefact, it can be reviewed, diffed and handed to whoever needs to see what a suite assumes about the upstream. 3. **Symmetry with the read.** Anything you can list you can import, which makes moving a configured set between servers a copy rather than a rewrite. ## Import is additive, not a reset The misconception worth naming is that import replaces the server's configuration. It does not: it registers what the document contains and does not, by itself, remove what was already registered. Clearing the set is WireMock's separate collection call, `DELETE /__admin/mappings`. So a fixture that means "the server should hold exactly these mappings and nothing else" is two calls, not one, and a fixture that imports twice without clearing has registered its mappings twice. | you want | the WireMock call | |---|---| | one mapping, id returned | `POST /__admin/mappings` | | many mappings, one round trip | `POST /__admin/mappings/import` | | read the whole registered set | `GET /__admin/mappings` | | empty the registered set | `DELETE /__admin/mappings` | ## Choosing between them The honest rule is about what happens after registration: - **Use the single POST** when the case needs the id back, when only one or two mappings are involved, or when each mapping is added at a different point in the scenario. - **Use import** when a whole fixture is installed once at the start of a run and is not addressed individually afterwards. - **Use import** when the mapping set is an artefact your team owns as a document, because the payload is exactly that document. - **Do not simulate import with a loop of single POSTs** and call it the same thing — it is N round trips, and it is slower for no gain when nothing needs the individual ids. - **Do not rely on import to tidy up.** If the server must end up holding only what you are importing, clear the collection first. ## What the admin API is not doing here Neither route interprets the mappings for you beyond storing them. The matchers that decide which lighthouse request selects which mapping, and the canned reply the mapping produces, are the content of the objects you are posting and a subject in their own right. The admin API's contribution is that the content arrives **while the server is running** and can be read back afterwards. If you need the ids of imported mappings — to change one lighthouse station's reply mid-run, say — you get them by reading the collection with WireMock's `GET /__admin/mappings` and finding the entries you recognise, not by inferring them from the order of the document you sent.

  • How do you get the ids of the mappings an import loaded?
    Read them back with `GET /__admin/mappings`, which lists the registered set with each mapping's id. Import is a bulk load, so the reliable way to address one of the mappings it created is to look it up in the collection rather than infer it from the order of the document. If a case needs one specific mapping by id, registering that one with `POST /__admin/mappings` is simpler.
  • When is registering stubs one POST at a time still the better choice?
    When the case needs the id back immediately, when only one or two mappings are involved, or when each mapping is added at a different point in the scenario. Import wins on a large fixture installed once; single POSTs win when the registration belongs to the test's narrative and each stub must be removable on its own.

Registering stubs one POST at a time is filing index cards into a drawer one by one, keeping the receipt for each. Import hands over the whole box in a single trip — faster, but you have no receipts unless you go and read the drawer afterwards.

saying these in an interview costs you the question

  • Thinks import replaces everything already registered
  • Believes import accepts only a single mapping object
  • Expects import to read files from the server's disk
  • Loops single POSTs and calls that an import
  • Cannot say what document GET /__admin/mappings returns