Responses

A spec-based mock answers from the operation a request matches. Given the same document and the same request, it gives the same answer, so tests stay stable. Generated bodies use the same sample generator as your published API document.

How a response is chosen

Status. The lowest declared 2xx. If there is none, the first declared status, or default as 200.

Media type. The best match for the Accept header, honoring */*, type/* and q values. With no Accept header, application/json if declared, otherwise the first one. If nothing matches, the answer is 406. A response that declares no content has an empty body.

Body, in this order:

1. The media type’s example
2. The first entry of the media type’s examples
3. The schema’s example, or the first of its examples
4. A body generated from the schema

Generated bodies are deterministic. They honor format, enum, default, readOnly, writeOnly and allOf, and take the first choice of oneOf and anyOf.

Headers. Response headers the document declares, with their example or a sampled value, plus Content-Type and x-apigit-mock-operation, which names the operation that answered.

Control a response with the Prefer header

Combine preferences with commas, for example Prefer: code=200, example=sold.

The code, example and dynamic preferences use the same conventions as Prism, so tests written for Prism carry over.

# exercise your client's error handling
curl -i https://petstore-sandbox.mockserver.apigit.com/api/v3/pet/1 \
  -H 'api_key: anything' -H 'Prefer: code=404'

HTTP/2 404
content-type: application/json

Asking for something the operation does not declare is an error, not a silent fallback:

{
  "type": "https://apigit.com/mock/problems/unknown-status",
  "title": "The operation does not declare this status",
  "status": 422,
  "detail": "The operation does not declare status 418. Declared: 200, 400, 404.",
  "declared": ["200", "400", "404"]
}

Matching requests

• Literal path segments win over parameters, so /pets/mine wins over /pets/{id}.
• A path with no operation answers 404. A path that exists without that method answers 405 with an Allow header.
• HEAD without its own operation is answered by the GET operation, without a body.
• Browser cross-origin requests work: preflight OPTIONS requests are answered, and responses carry Access-Control-Allow-Origin.

Limits on generated bodies

Larger minItems and minLength values are reduced to fit. A response that still cannot be generated answers 500 unsupported-mock. These limits apply to generated bodies, not to examples you wrote.