Skip to main content
This page provides practical examples of common GraphQL operations for managing your Minecraft servers.

Try These Examples

Copy and paste these examples directly into the GraphQL Playground to test them live

​
Server Management

​
Get All Servers

query GetAllServers {
  servers {
    id
    name
    status
    players {
      online
      max
    }
    version
    createdAt
  }
}

​
Get Server Details

query GetServerDetails($serverId: ID!) {
  server(id: $serverId) {
    id
    name
    status
    players {
      online
      max
      list {
        uuid
        name
        online
        lastSeen
      }
    }
    configuration {
      server {
        name
        maxPlayers
        version
        motd
        difficulty
      }
      world {
        name
        seed
        generator
      }
    }
    createdAt
  }
}

​
Start a Server

mutation StartServer($serverId: ID!) {
  startServer(serverId: $serverId) {
    success
    message
    server {
      id
      status
    }
  }
}

​
Stop a Server

mutation StopServer($serverId: ID!) {
  stopServer(serverId: $serverId) {
    success
    message
    server {
      id
      status
    }
  }
}

​
Player Management

​
Get Online Players

query GetOnlinePlayers($serverId: ID!) {
  server(id: $serverId) {
    players {
      list {
        uuid
        name
        online
        joinTime
        location {
          world
          x
          y
          z
        }
      }
    }
  }
}

​
Get Player History

query GetPlayerHistory($serverId: ID!, $playerId: ID!) {
  playerHistory(serverId: $serverId, playerId: $playerId) {
    player {
      uuid
      name
    }
    sessions {
      joinTime
      leaveTime
      duration
    }
    totalPlayTime
  }
}

​
Configuration Management

​
Get Server Configuration

query GetServerConfig($serverId: ID!) {
  server(id: $serverId) {
    configuration {
      server {
        name
        maxPlayers
        version
        motd
        difficulty
      }
      world {
        name
        seed
        generator
      }
    }
  }
}

​
Update Server Configuration

mutation UpdateServerConfig($serverId: ID!, $config: ServerConfigInput!) {
  updateServerConfig(serverId: $serverId, config: $config) {
    success
    message
    server {
      configuration {
        server {
          name
          maxPlayers
          motd
          difficulty
        }
      }
    }
  }
}

​
Real-time Subscriptions

​
Server Status Updates

subscription ServerStatusUpdates($serverId: ID!) {
  serverStatusChanged(serverId: $serverId) {
    id
    status
    players {
      online
      max
    }
    timestamp
  }
}

​
Player Join/Leave Events

subscription PlayerEvents($serverId: ID!) {
  playerEvents(serverId: $serverId) {
    type
    player {
      uuid
      name
    }
    timestamp
    data {
      ... on PlayerJoinEvent {
        joinTime
        location {
          world
          x
          y
          z
        }
      }
      ... on PlayerLeaveEvent {
        leaveTime
        sessionDuration
      }
    }
  }
}

​
Server Performance Metrics

subscription ServerMetrics($serverId: ID!) {
  serverMetrics(serverId: $serverId) {
    timestamp
    cpu {
      usage
      cores
    }
    memory {
      used
      total
      percentage
    }
    disk {
      used
      total
      percentage
    }
    network {
      bytesIn
      bytesOut
      packetsIn
      packetsOut
    }
  }
}

​
Advanced Queries

​
Complex Server Query

query GetServerWithAnalytics($serverId: ID!, $timeRange: TimeRange!) {
  server(id: $serverId) {
    id
    name
    status
    players {
      online
      max
      list {
        uuid
        name
        online
        lastSeen
        totalPlayTime
      }
    }
    configuration {
      server {
        name
        maxPlayers
        version
        motd
        difficulty
      }
      world {
        name
        seed
        generator
      }
    }
    analytics(timeRange: $timeRange) {
      playerActivity {
        totalSessions
        averageSessionDuration
        peakPlayers
        uniquePlayers
      }
      performance {
        averageCpuUsage
        averageMemoryUsage
        uptime
      }
    }
    createdAt
  }
}

​
Batch Operations

mutation BatchServerOperations($operations: [ServerOperation!]!) {
  batchServerOperations(operations: $operations) {
    results {
      operationId
      success
      message
      data
    }
    errors {
      operationId
      error
      message
    }
  }
}

​
Error Handling

GraphQL provides detailed error information in the response: 
{
  "data": null,
  "errors": [
    {
      "message": "Server not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["server"],
      "extensions": {
        "code": "SERVER_NOT_FOUND",
        "serverId": "invalid-id"
      }
    }
  ]
}

​
Best Practices

Always use variables for dynamic values instead of string interpolation:
# Good
query GetServer($id: ID!) {
  server(id: $id) { name }
}

# Bad
query GetServer {
  server(id: "hardcoded-id") { name }
}
Only request the fields you actually need to reduce payload size:
# Good - only name and status
query GetServerStatus($id: ID!) {
  server(id: $id) {
    name
    status
  }
}

# Bad - requesting everything
query GetServerStatus($id: ID!) {
  server(id: $id) {
    id
    name
    status
    players { online max }
    configuration { server { name } }
    createdAt
  }
}
Define reusable fragments for common field sets:
fragment ServerBasicInfo on Server {
  id
  name
  status
}

query GetServers {
  servers {
    ...ServerBasicInfo
  }
}