Expectations API

Create, update, and load expectations using PUT /mockserver/expectation and PUT /mockserver/openapi.

An expectation tells MockServer how to respond when an incoming request matches specific criteria. You submit expectations via PUT /mockserver/expectation with a JSON body describing the request matcher and the action to take.

PUT /mockserver/expectation

Create or update one or more expectations.

Returns: 201 Created on success, 400 Bad Request if the body is invalid.

You can submit a single expectation object or a JSON array of expectations. If you supply an id, MockServer updates the existing expectation with that ID or creates a new one — giving you stable, idempotent updates.

Request fields

id · string

Stable identifier for the expectation. Supply the same id to update an existing expectation in place. If omitted, MockServer generates a UUID.

priority · integer · default: "0"

Match priority. When multiple expectations match a request, MockServer uses the one with the highest priority. Expectations with equal priority are evaluated in the order they were added.

httpRequest · object

The request matcher. MockServer evaluates all properties you provide; any property you omit is not checked. Supports matching on method, path, pathParameters, queryStringParameters, headers, cookies, body, and socketAddress. You can also match against an OpenAPI spec by providing specUrlOrPayload (and optionally operationId) instead of individual fields.

httpResponse · object

Return a fixed HTTP response. Use this for the majority of mocking scenarios. Mutually exclusive with httpForward, httpClassCallback, httpError, httpResponseTemplate, and httpOverrideForwardedRequest.

httpForward · object

Forward the matched request to another host. Provide host, port, and scheme (HTTP or HTTPS).

httpOverrideForwardedRequest · object

Forward the request with modifications applied before forwarding and/or to the response before returning it.

httpClassCallback · object

Delegate response generation to a Java class on the classpath. Provide callbackClass with the fully-qualified class name.

httpResponseTemplate · object

Generate responses dynamically using a JavaScript or Velocity template. Provide template and templateType (JAVASCRIPT or VELOCITY).

httpError · object

Simulate a connection-level error. Set dropConnection: true to close the connection immediately, or provide responseBytes (base64-encoded) to send raw bytes before dropping.

times · object

Controls how many times this expectation can be matched. Omit for unlimited matching.

• remainingTimes (integer) — match at most this many more times
• unlimited (boolean) — if true, match indefinitely (overrides remainingTimes)

timeToLive · object

Controls how long the expectation remains active after it is created.

• timeUnit (string) — e.g. "SECONDS", "MINUTES", "HOURS"
• timeToLive (integer) — duration in the given unit
• unlimited (boolean) — if true, the expectation never expires

Basic response example

Match GET /view/cart and return a plain-text body:

curl

curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "method": "GET",
      "path": "/view/cart",
      "queryStringParameters": {
        "cartId": ["055CA455-1DF7-45BB-8535-4F83E7266092"]
      },
      "cookies": {
        "session": "4930456C-C718-476F-971F-CB8E047AB349"
      }
    },
    "httpResponse": {
      "body": "some_response_body"
    }
  }'

Limited-use expectation

Match a path exactly twice, then stop matching:

curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "path": "/some/path"
    },
    "httpResponse": {
      "body": "some_response_body"
    },
    "times": {
      "remainingTimes": 2,
      "unlimited": false
    },
    "timeToLive": {
      "unlimited": true
    }
  }'

Expectation with TTL

Match exactly once in the next 60 seconds:

curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "path": "/some/path"
    },
    "httpResponse": {
      "body": "some_response_body"
    },
    "times": {
      "remainingTimes": 1,
      "unlimited": false
    },
    "timeToLive": {
      "timeUnit": "SECONDS",
      "timeToLive": 60,
      "unlimited": false
    }
  }'

Update an expectation by ID

Supply an id to update an existing expectation or create a new one with a known identifier:

curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "id": "630a6e5b-9d61-4668-a18f-a0d3df558583",
    "priority": 0,
    "httpRequest": {
      "path": "/some/path"
    },
    "httpResponse": {
      "statusCode": 200,
      "body": "some_response_body"
    },
    "times": {
      "unlimited": true
    },
    "timeToLive": {
      "unlimited": true
    }
  }'

Bulk create

Submit an array of expectations in one call:

curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '[
    {
      "httpRequest": { "path": "/somePathOne" },
      "httpResponse": { "statusCode": 200, "body": "one" }
    },
    {
      "httpRequest": { "path": "/somePathTwo" },
      "httpResponse": { "statusCode": 200, "body": "two" }
    }
  ]'

Forward expectation

Forward matching requests to another host:

curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "path": "/some/path"
    },
    "httpForward": {
      "host": "mock-server.com",
      "port": 443,
      "scheme": "HTTPS"
    }
  }'

Error simulation

Drop the connection for requests matching a path:

curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "path": "/some/path"
    },
    "httpError": {
      "dropConnection": true
    }
  }'

---

PUT /mockserver/openapi

Load expectations automatically from an OpenAPI specification. MockServer generates one expectation per operation in the spec, using the spec’s request schema as the matcher.

Returns: 201 Created on success.

specUrlOrPayload · string · required

A URL pointing to an OpenAPI JSON or YAML file, a classpath resource path, or the raw spec content as a string.

operationsAndResponses · object

Override the response code used for each operation. Keys are operationId strings; values are HTTP status code strings (e.g. "200", "404"). If omitted, MockServer picks the first defined response for each operation.

Load from a URL

curl -X PUT "http://localhost:1080/mockserver/openapi" \
  -d '{
    "specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver/master/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json"
  }'

Load from a URL with custom response codes

curl -X PUT "http://localhost:1080/mockserver/openapi" \
  -d '{
    "specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver/master/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
    "operationsAndResponses": {
      "listPets": "200",
      "createPets": "201",
      "showPetById": "200"
    }
  }'

You can also match against OpenAPI operations inside a regular PUT /mockserver/expectation request by providing specUrlOrPayload (and optionally operationId) inside the httpRequest object. This lets you target a single operation while supplying a custom action.