Route Behavior

GraphQL

A GraphQL API sends every request to the same path and method — usually POST /graphql — so the usual method-and-path routing can't tell one operation from another. MockBase handles this with a dedicated match source, graphql_operation, that reads the request's operation name directly and lets you route on it like anything else.

Matching on the operation name

Add a match condition with source graphql_operation. There's no key to fill in — the value being compared is the operation name itself, extracted from the request body:

source: graphql_operation
operator: equals
value: GetUser

This works whether or not the client sends an explicit operationName field:

  • If the body has "operationName": "GetUser", that value is used directly.
  • Otherwise, MockBase parses the name straight out of the query text — the GetUser in query GetUser($id: ID!) { ... } — which covers plain fetch()/curl calls that only ever send {"query": "..."} and never set operationName at all.
  • An anonymous operation ({ hero { name } }, no query Name header in the text) has no name to extract, so exists on graphql_operation is a quick way to tell named and anonymous operations apart.

Every other part of a route still works exactly as normal on top of this: priority ordering, dynamic templates, chaos injection, delay — a GraphQL route is a route like any other, just matched on operation name instead of (or alongside) query/header/body conditions.

Returning GraphQL's error shape

GraphQL doesn't use HTTP status codes for application errors — a failed operation still comes back as 200, with the failure described inside an errors array, often alongside a partial data object. Since a route's response body is just JSON you write yourself, this is a normal route — there's nothing GraphQL-specific to configure beyond the body:

json
{
  "errors": [
    {
      "message": "Name for character with ID 1002 could not be fetched.",
      "locations": [{ "line": 6, "column": 7 }],
      "path": ["hero", "heroFriends", 1, "name"],
      "extensions": { "code": "CAN_NOT_FETCH_BY_ID" }
    }
  ],
  "data": { "hero": { "name": "R2-D2", "heroFriends": [{ "id": "1000", "name": "Luke Skywalker" }] } }
}

Give this route a higher priority and a graphql_operation condition matching the specific operation you want to fail, and leave a second, unconditioned POST /graphql route at lower priority for the normal, successful response. That combination — one endpoint, two routes, distinguished by operation name — is exactly what lets you exercise a client's error-handling path for one specific query without touching anything else that hits the same URL.

Try it

The GraphQL template is a working example of this exact pattern — a success route and a FailingQuery-only error route on the same /graphql path — ready to create with one click.

The same problem in SOAP

SOAP has the identical shape of problem — every operation posted to one URL — and MockBase solves it the same way, with a soap_body match source that reads values out of the XML envelope. See SOAP & XML.