GraphQL

Build and serve GraphQL mock APIs with full schema support, typed operations, and automatic response generation from your data models.

How GraphQL Works in MockAPI

MockAPI's GraphQL support consists of three components that work together:

Schemas: Define your GraphQL type system using the Schema Definition Language (SDL)
Operations: Map queries, mutations, and subscriptions to data models
Endpoints: Create URL paths where clients can send GraphQL requests

When a GraphQL request arrives, MockAPI parses the query, finds the matching operation, generates data from the linked model, and returns only the fields requested in the selection set.

GraphQL Schemas

A GraphQL schema defines the type system for your mock API using the standard GraphQL Schema Definition Language (SDL).

Creating a schema

Navigate to GraphQL → Schemas in the sidebar and click "New Schema".

Name: A descriptive name for your schema (e.g., "E-Commerce API")
Schema Definition: Write your GraphQL SDL in the built-in Monaco editor

Example schema

type User {
  id: ID!
  firstName: String!
  lastName: String!
  email: String!
  avatar: String
  createdAt: String!
}

type Post {
  id: ID!
  title: String!
  body: String!
  author: User!
  publishedAt: String!
}

type Query {
  users: [User!]!
  user(id: ID!): User
  posts: [Post!]!
  post(id: ID!): Post
}

type Mutation {
  createUser(firstName: String!, lastName: String!, email: String!): User!
  createPost(title: String!, body: String!, authorId: ID!): Post!
}

Schema validation

MockAPI validates your schema when you save it. The editor provides syntax highlighting and will flag errors in your SDL. Common issues include missing type definitions, invalid field types, or syntax errors.

Extracting operations

After creating a schema, MockAPI can automatically extract query, mutation, and subscription operations from your schema definition. This saves you from manually creating each operation. Use the "Extract Operations" feature on the schema detail page.

GraphQL Operations

Operations connect your GraphQL schema to data models. Each operation represents a query, mutation, or subscription that clients can execute.

Operation types

Type	Description	Example
Query	Read-only operations to fetch data	users, post(id: ID!)
Mutation	Operations that modify data	createUser, deletePost
Subscription	Real-time operations for data changes	onUserCreated, onPostUpdated

Creating an operation

From a schema's detail page, click "New Operation" to create an operation.

Name: The operation name (must match a field in your schema's Query, Mutation, or Subscription type)
Operation Type: Query, Mutation, or Subscription
Response Model: The data model to use for generating responses
Range: When enabled, returns an array of N items (for list queries)

Model mapping

Each operation is linked to a data model. When a client executes the operation, MockAPI generates response data from that model using the configured property types. The generated data respects the GraphQL selection set: only fields requested by the client are included in the response.

Client query with selection set

query {
  users {
    id
    firstName
    email
  }
}

Response (only selected fields)

{
  "data": {
    "users": [
      { "id": "1", "firstName": "John", "email": "john@example.com" },
      { "id": "2", "firstName": "Jane", "email": "jane@example.com" }
    ]
  }
}

GraphQL Endpoints

GraphQL endpoints define the URL paths where clients send their GraphQL requests. An endpoint links a URL path to a specific schema.

Creating a GraphQL endpoint

Navigate to GraphQL → Endpoints in the sidebar and click "New Endpoint".

Path: The URL path (e.g., /graphql)
Schema: The schema this endpoint uses
Description: Optional description of the endpoint

Consuming Your GraphQL API

To make requests to your mock GraphQL API, send a POST request to the endpoint path with your GraphQL query in the request body. You'll need to include your API key. See Authentication for all supported methods.

Base URL

All GraphQL endpoints are served from the same base URL. Prepend your endpoint path to construct the full request URL:

GraphQL API Base URL

https://graphql.mockapi.com

For an endpoint path of /graphql, the full URL is https://graphql.mockapi.com/graphql. Send POST requests with your query in the JSON body.

Request format

cURL

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ users { id firstName email } }"}' \
  https://graphql.mockapi.com/graphql

JavaScript (fetch)

const response = await fetch('https://graphql.mockapi.com/graphql', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: `
      query {
        users {
          id
          firstName
          lastName
          email
        }
      }
    `,
  }),
});

const { data } = await response.json();
console.log(data.users);

Variables

You can send variables alongside your query:

Request with variables

{
  "query": "query GetUser($id: ID!) { user(id: $id) { id firstName email } }",
  "variables": {
    "id": "42"
  },
  "operationName": "GetUser"
}

Named operations

When your query document contains multiple operations, use the operationName field to specify which operation to execute. MockAPI uses the operation name to find the matching operation configuration and its associated model.

Schema-Model Synchronization

MockAPI includes an intelligent synchronization system that detects discrepancies between your GraphQL schemas and data models. When a model changes, MockAPI identifies mismatches and notifies you so you can keep your schema in sync.

Discrepancy types

Type	Description
Field Added	A new field was added to the model but is missing from the schema
Field Removed	A field was removed from the model but still exists in the schema
Type Changed	A field's type was changed in the model but not updated in the schema
Required Changed	A field's required status was changed
Array Changed	A field was changed between single value and array

Resolving discrepancies

When discrepancies are detected, you can:

Apply: Automatically update the schema to match the model changes
Dismiss: Acknowledge the discrepancy without making changes

Notifications appear in your notification center and on the schema detail page.

Best Practices

Keep schemas and models in sync: Use the schema-model sync feature to detect and resolve mismatches early. You can also test your queries in the API Playground.
Use extract operations: Let MockAPI automatically create operations from your schema to save time.
Map list queries to range operations: Enable range on operations that return lists (e.g., users) so they return arrays.

REST API MCP (AI Integration)