Skip to main content

​
Introduction

The RealtimeChat GraphQL API provides a flexible and efficient way to interact with the real-time messaging platform. Built with HotChocolate, it offers queries, mutations, and subscriptions for comprehensive chat functionality.
RealtimeChat uses a hybrid API architecture: GraphQL for chat operations (messages, chat rooms, subscriptions) and REST for authentication endpoints. See the Authentication Overview for REST authentication endpoints.

Queries

Fetch chat rooms, messages, and search through message history

Mutations

Send, edit, and delete messages in real-time

Subscriptions

Subscribe to real-time message updates via WebSocket

Schema

Type-safe GraphQL schema with strongly-typed models

​
GraphQL Endpoint

The GraphQL API is available at: 
POST /graphql
For subscriptions (WebSocket): 
WS /graphql

​
GraphQL Playground

RealtimeChat includes Banana Cake Pop, an interactive GraphQL IDE that allows you to:
  • Explore the complete GraphQL schema
  • Test queries, mutations, and subscriptions
  • View documentation for all types and fields
  • Debug GraphQL requests in real-time
Access the playground at: 
http://localhost:5000/graphql
The GraphQL playground is only available in development mode.

​
Making GraphQL Requests

​
Using cURL

curl -X POST http://localhost:5000/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { getChatRooms { id name } }"
  }'

​
Using HTTP Client

const response = await fetch('http://localhost:5000/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: `
      query {
        getChatRooms {
          id
          name
        }
      }
    `,
  }),
});

const data = await response.json();

​
Authentication

Currently, the GraphQL API does not require authentication. In production environments, you should implement:
  • JWT token authentication
  • API key validation
  • Role-based access control
Authentication requirements may be added in future versions of the API.

​
Error Handling

GraphQL errors follow the standard GraphQL error format: 
{
  "errors": [
    {
      "message": "Error message here",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["getChatRoom"],
      "extensions": {
        "code": "ENTITY_NOT_FOUND"
      }
    }
  ],
  "data": null
}

​
Common Error Types

​
ENTITY_NOT_FOUND
The requested entity (chat room, message, etc.) does not exist
​
VALIDATION_ERROR
Input validation failed (e.g., invalid parameters)
​
INTERNAL_SERVER_ERROR
An unexpected error occurred on the server

​
Rate Limiting

Currently, there are no rate limits enforced on the GraphQL API. For production deployments, consider implementing:
  • Query complexity analysis
  • Request rate limiting
  • Query depth limiting
  • Query cost calculation

​
Response Format

All GraphQL responses follow this structure: 
{
  "data": {
    // Your query results
  },
  "errors": [
    // Optional errors array
  ]
}

​
Next Steps

Queries

Learn about available queries

Mutations

Explore mutation operations

Subscriptions

Set up real-time subscriptions

Build docs developers (and LLMs) love

Get started for freeTalk to us