GraphQL Mock Servers

A hosted spec-based mock can serve a GraphQL schema alongside OpenAPI documents. The schema is another document of the same mock, with its own base path. Documents share the mock’s access control, quota and request logs. It is not a third mock-server type.

Add a complete SDL schema

Commit a .graphql or .gql file to your repository. The file must contain a complete schema with a query root and the types it uses; it is not stitched together from separate schema files.

type Product {
  id: ID!
  name: String!
  price: Float!
}
 
type Query {
  product(id: ID!): Product
  products: [Product!]!
}
 
type Mutation {
  createProduct(name: String!): Product!
}

Publish the hosted mock

1. Open Publish → Publish MockServer from the repository branch or commit.
2. Choose Spec-based and select schema.graphql under Documents & Base Paths.
3. Keep the prefilled /graphql base path, or choose another unique base path.
4. Choose the mock’s name and access settings, then publish it.

The schema answers at the base path itself, for example https://catalog-sandbox.mockserver.apigit.com/graphql. Do not append a GraphQL field name to the URL.

After the backend rollout, the CLI can publish the same schema from a commit already pushed to APIGit:

apigit mock publish --name catalog-sandbox --type spec --mount schema.graphql:/graphql

This publishes a hosted mock. It does not start a local GraphQL server. The CLI’s --name option still follows your plan’s naming rules; see Publish a Mock Server.

Send a query

Use POST with a JSON object containing query, optional variables and optional operationName:

curl https://catalog-sandbox.mockserver.apigit.com/graphql \
  -H 'Content-Type: application/json' \
  --data '{"query":"query Product($id: ID!) { product(id: $id) { id name price } }","variables":{"id":"42"},"operationName":"Product"}'

For the schema above, the response is:

{
  "data": {
    "product": {
      "id": "42",
      "name": "Example",
      "price": 1.5
    }
  }
}

Queries can also use GET with URL-encoded query, variables and operationName parameters. Mutations require POST. A protected mock requires the same APIGIT-Token header as an OpenAPI mock; see access control.

How values are generated

• Responses follow the selected fields and schema types, with fixed values for scalar fields.
• Lists contain two generated items. Enums use their first declared value; interfaces and unions use their first available concrete type.
• An argument matching a returned field is echoed, such as product(id: "42") { id } returning "42".
• Repeating a request produces the same values. Introspection is supported.

This engine generates values from the schema. It does not use OpenAPI examples, the Prefer response-selection header, or JavaScript resolvers supplied by you.

Validation and limits

The engine parses and validates each query against the schema before executing it. Malformed or invalid queries return 400 with GraphQL errors. Execution results use the GraphQL data/errors response shape.

Subscriptions and batched requests return errors. Mutations return generated results but do not store state or change later query results. A mutation sent with GET returns 405.

OpenAPI request-validation switches do not control GraphQL validation. Plan quotas, access settings and request logs belong to the whole mock server. For custom stateful behavior, use a code-based mock.

See Supported API Formats for the rollout boundary and Documents and base paths for sharing a mock with OpenAPI documents.