Skip to content

Admin API Reference

Jump to bottom
Noah Lerner edited this page Feb 2, 2020 · 52 revisions

Admin API Reference

The WireMock admin API provides functionality to define the mappings via a http/https interface. To use this interface, you need to enable the admin interface in code:

var server = WireMockServer.StartWithAdminInterface();

API definition

A Swagger 2.0 definition can be found on swagger hub.

Client API

You can use a predefined interface API (WireMock.Net.RestClient) to access all the methods described on this page.

// Create an implementation of the IWireMockAdminApi and pass in the base URL for the API.
var api = RestClient.For<IWireMockAdminApi>("http://localhost:9091");

// Set BASIC Authorization
api.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("foo:bar")));

// Call API
var settings = await api.GetSettingsAsync();

Supported interfaces

The following interfaces are supported:

/__admin/settings

The global settings from the mock service.

  • GET /__admin/settings --> Gets the current global settings
  • POST /__admin/settings --> Updates the current global settings

/__admin/mappings

The mappings defined in the mock service.

  • GET /__admin/mappings --> Gets all defined mappings
  • POST /__admin/mappings --> Create a new single stub mapping or an array from mappings
  • DELETE /__admin/mappings or POST /__admin/mappings/reset --> Delete all stub mappings
  • DELETE /__admin/mappings with array of json mappings/GUIDs in body --> Delete stub mappings matching the specified GUIDs.
  • GET /__admin/mappings/{guid} --> Get a single stub mapping
  • PUT /__admin/mappings/{guid} --> Update a stub mapping
  • DELETE /__admin/mappings/{guid} --> Delete a single stub mapping
  • POST /__admin/mappings/save --> Save all persistent stub mappings to the backing store

/admin/files

The files which can be used in the mappings.

  • HEAD /__admin/files/{filename.ext} --> Checks if the file named {filename.ext} does exist.
  • POST /__admin/files/{filename.ext} --> Creates a new file named {filename.ext} in the mappings folder on disk.
  • PUT /__admin/files/{filename.ext} --> Updates an existing file named {filename.ext} in the mappings folder on disk.
  • GET /__admin/files/{filename.ext} --> Get the content from the file named {filename.ext} in the mappings folder on disk.
  • DELETE /__admin/files/{filename.ext} --> Deletes a new file named {filename.ext} from the mappings folder on disk.

/__admin/requests

Logged requests and responses received by the mock service.

  • GET /__admin/requests --> Get received requests
  • DELETE /__admin/requests or POST /__admin/requests/reset --> Delete all received requests
  • GET /__admin/requests/{guid} --> Get a single request
  • POST /__admin/requests/count --> TODO
  • POST /__admin/requests/find --> Find requests
  • GET /__admin/requests/unmatched --> TODO
  • GET /__admin/requests/unmatched/near-misses --> TODO

For some example requests, see this PostMan Collection

/__admin/mappings

The mappings defined in the mock service.

GET /__admin/mappings

Gets all defined mappings.

Example request: GET http://localhost/__admin/mappings

Example response:

[
  {
    "Guid": "be6e1db8-cb95-4a15-a836-dcd0092b34a0",
    "Request": {
      "Path": {
        "Matchers": [
          {
            "Name": "WildcardMatcher",
            "Pattern": "/data"
          }
        ]
      },
      "Methods": [
        "get"
      ],
      "Headers": [
        {
          "Name": "Content-Type",
          "Matchers": [
            {
              "Name": "WildcardMatcher",
              "Pattern": "application/*"
            }
          ]
        }
      ],
      "Cookies": [],
      "Params": [
        {
          "Name": "start",
          "Values": [ "1000", "1001" ]
        }
      ],
      "Body": {}
    },
    "Response": {
      "StatusCode": 200,
      "Body": "{ \"result\": \"Contains x with FUNC 200\"}",
      "UseTransformer": false,
      "Headers": {
        "Content-Type": "application/json"
      }
    }
  },
  {
    "Guid": "90356dba-b36c-469a-a17e-669cd84f1f05",
    "Request": {
      "Path": {
        "Matchers": [
          {
            "Name": "WildcardMatcher",
            "Pattern": "/*"
          }
        ]
      },
      "Methods": [
        "get"
      ],
      "Headers": [],
      "Cookies": [],
      "Params": [
        {
          "Name": "start",
          "Values": []
        }
      ],
      "Body": {}
    },
    "Response": {
      "StatusCode": 200,
      "Body": "{\"msg\": \"Hello world, {{request.path}}\"",
      "UseTransformer": true,
      "Headers": {
        "Transformed-Postman-Token": "token is {{request.headers.Postman-Token}}",
        "Content-Type": "application/json"
      },
      "Delay": 10
    }
  }
]

POST /__admin/mappings

Create a new stub mapping

Example request:

{
    "Guid": "dae02a0d-8a33-46ed-aab0-afbecc8643e3",
    "Request": {
      "Url": "/testabc",
      "Methods": [
        "put"
      ],
      "Headers": [
        {
          "Name": "Content-Type",
          "Matchers": [
            {
              "Name": "WildcardMatcher",
              "Pattern": "application/*"
            }
          ]
        }
      ],
      "Cookies": [],
      "Params": [
        {
          "Name": "start",
          "Values": [ "1000", "1001" ]
        }
      ],
       "Body": {
        "Matcher": {
          "Name": "JsonPathMatcher",
          "Pattern": "$.things[?(@.name == 'RequiredThing')]"
        }
      }
    },
    "Response": {
      "UseTransformer": true,
      "StatusCode": 205,
      "BodyAsJson": { "result": "test - {{request.path}}" },
      "Headers": {
        "Content-Type": "application/json", "a" : "b"
      },
      "Delay": 10
    }
  }

Create a new stub mapping and save this to disk. Example request:

{
    "Guid": "dae02a0d-8a33-46ed-aab0-afbecc864344",
    "SaveToFile": true,
    "Title": "the_filename",
    "Request": {
      "Url": "/example",
      "Methods": [
        "get"
      ]
    },
    "Response": {
      "BodyAsJson": { "result": "ok" }
    }
  }

Note : It's also possible to pre-load Mappings. This can be done by putting a file named {guid}.json in the __admin\mapping directory.

Example : 11111110-a633-40e8-a244-5cb80bc0ab66.json

{
    "Request": {
        "Path": {
            "Matchers": [
                {
                    "Name": "WildcardMatcher",
                    "Pattern": "/static/mapping"
                }
            ]
        },
        "Methods": [
            "get"
        ]
    },
    "Response": {
        "BodyAsJson": { "body": "static mapping" },
        "Headers": {
            "Content-Type": "application/json"
        }
    }
}

DELETE /__admin/mappings

Delete all stub mappings.

DELETE /__admin/mappings

Delete all stub mappings matched to the GUIDs in the body of request. NOTE: AllowBodyForAllHttpMethods must be set to true in Admin Settings for this feature to work. Otherwise, body will arrive to the service empty and delete all stub mappings.

Delete an existing stub mapping (identical to the POST request, but deletes instead of create)

Example request:

{
    "Guid": "dae02a0d-8a33-46ed-aab0-afbecc8643e3",
    "Request": {
      "Url": "/testabc",
      "Methods": [
        "put"
      ],
      "Headers": [
        {
          "Name": "Content-Type",
          "Matchers": [
            {
              "Name": "WildcardMatcher",
              "Pattern": "application/*"
            }
          ]
        }
      ],
      "Cookies": [],
      "Params": [
        {
          "Name": "start",
          "Values": [ "1000", "1001" ]
        }
      ],
       "Body": {
        "Matcher": {
          "Name": "JsonPathMatcher",
          "Pattern": "$.things[?(@.name == 'RequiredThing')]"
        }
      }
    },
    "Response": {
      "UseTransformer": true,
      "StatusCode": 205,
      "BodyAsJson": { "result": "test - {{request.path}}" },
      "Headers": {
        "Content-Type": "application/json", "a" : "b"
      },
      "Delay": 10
    }
  }

This is also valid syntax for the request (demonstrates multi-delete):

[{ "Guid": "dae02a0d-8a33-46ed-aab0-afbecc8643e3" }, { "Guid": "c181c4f6-fe48-4712-8390-e1a4b358e278" }]

GET /__admin/mappings/{guid}

Get a single stub mapping

PUT /__admin/mappings/{guid}

Update a single stub mapping

Example request

{
  "Request": {
    "Path": {
      "Matchers": []
    },
    "Methods": [
      "get"
    ],
    "Headers": [],
    "Cookies": [],
    "Params": [
      {
        "Name": "start",
        "Values": []
      }
    ],
    "Body": {}
  },
  "Response": {
    "StatusCode": 205,
    "BodyAsJson": { "msg": "Hello world!!" },
    "BodyAsJsonIndented": true,
    "UseTransformer": true,
    "Headers": {
      "Transformed-Postman-Token": "token is {{request.headers.Postman-Token}}",
      "Content-Type": "application/json"
    }
  }
}

DELETE /__admin/mappings/{guid}

Delete a single stub mapping.

POST /__admin/mappings/save

Save all persistent stub mappings to the backing store

/__admin/requests

Logged requests and responses received by the mock service.

GET /__admin/requests

Get received requests

DELETE /__admin/requests

Delete all received requests

GET /__admin/requests/{guid}

Get a single request.

POST /__admin/requests/count --> TODO

POST /__admin/requests/find

Find requests based on a criteria.

Example request:

{
  "Path": {
        "Matchers": [
          {
            "Name": "WildcardMatcher",
            "Pattern": "/testjson"
          }
        ]
      }
}

GET /__admin/requests/unmatched --> TODO

GET /__admin/requests/unmatched/near-misses --> TODO

Pages

Clone this wiki locally