Skip to content

A GraphQL mock server from a schema file, in one command

Last checked and updated

apigit mock serve schema.graphql starts a GraphQL endpoint on your machine from a schema file alone: no resolvers, no data. Every query and mutation the schema allows is answered with values of the right types, and a query the schema does not allow is refused with a GraphQL errors answer. It runs offline and needs no account.

Start it

type Product {
  id: ID!
  name: String!
  price: Float!
  tags: [String!]!
}

type Query {
  product(id: ID!): Product
  products: [Product!]!
}

type Mutation {
  createProduct(name: String!): Product!
}
$ npm install -g @apigit/cli
$ apigit mock serve schema.graphql --port 4651
GraphQL mock of schema.graphql at http://127.0.0.1:4651/graphql (Ctrl+C to stop). POST {"query": "..."} there, or GET with ?query=; the answers have the shape of the schema with made-up values.

The file must be a complete schema with a query root. The default port is 4010.

What it answers

$ curl -X POST http://127.0.0.1:4651/graphql -H 'content-type: application/json' \
    -d '{"query":"{ products { id name price tags } }"}'
{"data":{"products":[{"id":"1","name":"Example","price":1.5,"tags":["string","string"]},{"id":"1","name":"Example","price":1.5,"tags":["string","string"]}]}}

Only the fields the query asks for come back, lists have two items, and the values are stable placeholders: "1" for an ID, 1.5 for a Float. They are the same on every call, which makes the mock usable in tests.

A mutation is answered with its return type, and an argument is echoed into the field of the same name:

$ curl ... -d '{"query":"mutation { createProduct(name: \"Lamp\") { id name } }"}'
{"data":{"createProduct":{"id":"1","name":"Lamp"}}}

Nothing is stored: a following products query does not contain the lamp.

It validates queries

A field the schema does not have is refused with GraphQL's errors list, which names the field and its position in the query. This mock sends it with status 400 (the GraphQL-over-HTTP draft suggests 422 for a validation failure, so do not test for the exact code):

$ curl -i ... -d '{"query":"{ products { colour } }"}'
HTTP/1.1 400 Bad Request

{"errors":[{"message":"Cannot query field \"colour\" on type \"Product\".","locations":[{"line":1,"column":14}]}]}

A query that does not parse gets a syntax error in the same form. So a frontend built against the mock cannot depend on a field that the schema, and later the real server, does not have.

What it does not do

Not mockedUse instead
Subscriptions: one sent to the mock gets 400, "Subscriptions are not mocked: this mock answers queries and mutations over HTTP."a real server or a scripted stub
State: created objects that show up in later queriesa scripted mock with state
Chosen example values per fieldthe generated values are fixed; put realistic data in a scripted mock
A schema stitched from several files: the command refuses to start ("not a valid GraphQL schema: Unknown type ...")one complete SDL file

Local or hosted

The same schema can be published as a hosted mock (apigit mock publish, or the Publish dialog in the browser), which gives a team or a CI job one shared address with a request log. The local command runs a copy of the hosted mock's engine, so a query that works locally works there. For REST descriptions the same command takes an OpenAPI file: run a mock server from an OpenAPI file.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish