The Data APIs: REST, GraphQL, and WebSockets for MongoDB

Your application needs to talk to your database. Traditionally, this means writing API endpoints, handling queries, managing connections, validating inputs, formatting responses... lots of code before you store or retrieve your first piece of data.

RESTHeart Cloud provides complete data APIs over MongoDB - REST, GraphQL, and WebSocket APIs, ready to use from day one.

Three APIs, One Database

RESTHeart Cloud gives you three different ways to access your MongoDB data. Use one, use all three - whatever fits your application best.

REST API provides traditional HTTP requests for straightforward CRUD operations and queries. GraphQL API offers flexible queries that fetch exactly what you need in a single request. WebSocket API enables real-time bidirectional communication for live updates and subscriptions.

All three APIs access the same MongoDB database. Choose the API that fits each part of your application.

REST API: The Universal Choice

REST APIs are everywhere. Every programming language, framework, and platform knows how to make HTTP requests.

What You Can Do

Create Documents

Creating new documents is straightforward with a simple POST request:

curl -X POST https://your-service.restheart.cloud/api/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello World", "author": "Alice"}'
content_copy

Read Documents

Reading documents offers several patterns. Get all documents with a simple GET request:

# Get all documents
curl https://your-service.restheart.cloud/api/messages \
  -H "Authorization: Bearer $TOKEN"

# Get specific document
curl https://your-service.restheart.cloud/api/messages/123 \
  -H "Authorization: Bearer $TOKEN"

# Query with filters
curl "https://your-service.restheart.cloud/api/messages?filter={'author':'Alice'}" \
  -H "Authorization: Bearer $TOKEN"
content_copy

Update Documents

Updating existing documents uses PATCH for partial updates:

curl -X PATCH https://your-service.restheart.cloud/api/messages/123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Updated message"}'
content_copy

Delete Documents

Deleting documents requires only the document identifier:

curl -X DELETE https://your-service.restheart.cloud/api/messages/123 \
  -H "Authorization: Bearer $TOKEN"
content_copy

Advanced Queries

Beyond basic CRUD, REST APIs support sophisticated query patterns. Sorting, pagination, and projection let you control exactly what data returns:

# Sort by date, limit results, select fields
curl "https://your-service.restheart.cloud/api/messages?sort={'date':-1}&pagesize=10&keys={'text':1,'author':1}" \
  -H "Authorization: Bearer $TOKEN"
content_copy

Aggregation pipelines enable complex data aggregations:

# Complex data aggregations
curl -X POST https://your-service.restheart.cloud/api/messages/_aggrs/stats \
  -H "Authorization: Bearer $TOKEN"
content_copy

Full-text search works across text fields:

# Search across text fields
curl "https://your-service.restheart.cloud/api/messages?filter={'$text':{'$search':'hello'}}" \
  -H "Authorization: Bearer $TOKEN"
content_copy

Learn REST API

Complete documentation and tutorial are available at https://restheart.org/docs/mongodb-rest/tutorial for comprehensive REST API coverage.

GraphQL API: Query What You Need

GraphQL lets you request exactly the data you need. No over-fetching, no under-fetching, just the perfect query.

What You Can Do

Query Documents

GraphQL queries specify exactly which fields to return:

{
  messages(filter: {author: "Alice"}) {
    _id
    text
    author
    date
  }
}
content_copy

Nested Relationships

GraphQL excels at fetching related data in a single query:

{
  users {
    _id
    name
    messages {
      text
      date
    }
  }
}
content_copy

Filtered and Sorted

Combine filtering, sorting, and limiting in flexible ways:

{
  messages(
    filter: {author: "Alice"}
    sort: {date: -1}
    limit: 10
  ) {
    _id
    text
    date
  }
}
content_copy

Mutations

Mutations modify data through GraphQL:

mutation {
  createMessage(input: {
    text: "Hello from GraphQL"
    author: "Bob"
  }) {
    _id
    text
  }
}
content_copy

GraphQL App Definitions

RESTHeart Cloud GraphQL APIs require you to define a GraphQL app with types and field mappings. You create an app definition that describes your data schema and how it maps to MongoDB collections. Once defined, your GraphQL API is ready to use with the exact structure you specified.

From Your Frontend

Using GraphQL from your frontend is straightforward with fetch:

// Using fetch
const query = `{
  messages(filter: {author: "Alice"}) {
    _id
    text
    author
  }
}`;

const response = await fetch('https://your-service.restheart.cloud/graphql', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query })
});

const data = await response.json();
content_copy

Or use Apollo Client, URQL, or any GraphQL client library for more sophisticated needs.

Learn GraphQL API

Complete documentation and tutorial are available at https://restheart.org/docs/mongodb-graphql/tutorial for comprehensive GraphQL API coverage.

WebSocket API: Real-Time Updates

WebSocket APIs enable real-time, bidirectional communication. Perfect for live updates, notifications, chat features, and collaborative editing.

What You Can Do

Subscribe to Changes

WebSocket connections provide instant updates when data changes:

// Connect to WebSocket
const ws = new WebSocket('wss://your-service.restheart.cloud/api/messages', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

// Receive real-time updates
ws.onmessage = (event) => {
  const change = JSON.parse(event.data);
  console.log('Document changed:', change);
  
  // Update your UI immediately
  updateUI(change);
};
content_copy

MongoDB Change Streams

RESTHeart Cloud WebSocket APIs use MongoDB Change Streams under the hood, providing powerful real-time capabilities. You get real-time notifications of inserts, updates, and deletes. Full document information is included in each change notification. Before and after values show what changed. Transaction support ensures consistent multi-document operations.

Filtered Subscriptions

Subscribe only to changes matching your filter criteria:

// Only receive changes matching your filter
const ws = new WebSocket(
  'wss://your-service.restheart.cloud/api/messages?filter={"author":"Alice"}',
  { headers: { 'Authorization': `Bearer ${token}` } }
);
content_copy

Real-Time Use Cases

Live Chat

Building chat requires coordinating message creation with real-time delivery:

// Send message via REST
await fetch('https://your-service.restheart.cloud/api/messages', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({ text: 'Hello!', author: 'Alice' })
});

// Everyone subscribed via WebSocket receives update instantly
content_copy

Collaborative Editing

Multiple users editing the same document see each other's changes in real-time without polling or manual refresh.

Live Dashboards

Data updates push to all connected clients immediately, keeping dashboards current without constant polling.

Notifications

Critical events trigger instant notifications to subscribed users, ensuring timely awareness of important changes.

Learn WebSocket API

Complete documentation and tutorial are available at https://restheart.org/docs/mongodb-websocket/tutorial for comprehensive WebSocket API coverage.

Using Multiple APIs Together

The power comes from combining APIs based on each use case's needs.

Example: Real-Time Todo App

A complete todo application demonstrates how APIs work together. Initial load uses REST or GraphQL to fetch existing todos:

// Fetch todos on page load
const response = await fetch('https://your-service.restheart.cloud/api/todos');
const todos = await response.json();
content_copy

Live updates use WebSocket to keep all clients synchronized:

// Subscribe to changes
const ws = new WebSocket('wss://your-service.restheart.cloud/api/todos');
ws.onmessage = (event) => {
  const change = JSON.parse(event.data);
  // Update UI with real-time changes
};
content_copy

Creating todos uses REST for straightforward mutations:

// User creates todo
await fetch('https://your-service.restheart.cloud/api/todos', {
  method: 'POST',
  body: JSON.stringify({ text: 'New todo', done: false })
});
// WebSocket subscribers receive update automatically
content_copy

Choosing Your API

Use REST when you need simple CRUD operations, traditional request-response patterns, maximum compatibility, or direct HTTP requests. REST's universality makes it the default choice for standard data operations.

Use GraphQL when you have complex data requirements, need to fetch related data, want flexible queries, or reducing over-fetching is important. GraphQL shines when data relationships are complex and query flexibility matters.

Use WebSocket when real-time updates are required, bidirectional communication is needed, live notifications matter, or you're building collaborative features. WebSocket enables the real-time experiences users expect from modern applications.

Use all three when building a complete application with various needs. Mix and match based on each feature's requirements for optimal results.

Authentication Works Everywhere

All three APIs support the same authentication methods. Basic Authentication, JWT tokens, and cookie-based auth work consistently across all APIs.

// Same token works for all APIs
const token = 'your-jwt-token';

// REST
fetch('https://your-service.restheart.cloud/api/data', {
  headers: { 'Authorization': `Bearer ${token}` }
});

// GraphQL
fetch('https://your-service.restheart.cloud/graphql', {
  headers: { 'Authorization': `Bearer ${token}` }
});

// WebSocket
new WebSocket('wss://your-service.restheart.cloud/api/data', {
  headers: { 'Authorization': `Bearer ${token}` }
});
content_copy

Permissions Apply Consistently

Your permission rules work across all APIs consistently. REST queries are filtered by permissions. GraphQL queries are filtered by permissions. WebSocket subscriptions are filtered by permissions.

Define permissions once, and they apply everywhere, ensuring consistent security across your entire application.

Start Using the Data APIs

1. Create Your Service

Sign up at https://cloud.restheart.com and create a free service to get started immediately.

2. Choose Your Tutorial

Select the tutorial that matches your preferred API style. The REST API Tutorial covers traditional HTTP APIs. The GraphQL API Tutorial explores flexible queries. The WebSocket API Tutorial demonstrates real-time features.

3. Build Your Application

Start making API calls immediately. No backend code required - the APIs are ready and waiting for your application.

Why This Matters

The traditional approach requires significant work. Write API endpoints for every operation. Handle query parsing and validation. Implement filtering, sorting, and pagination. Set up WebSocket server infrastructure. Write GraphQL resolvers for each type. Maintain all this code as requirements change.

The RESTHeart Cloud approach eliminates this work. APIs already exist for all operations. All operations are supported out of the box. Filtering, sorting, and pagination are built-in. WebSocket just works without configuration. GraphQL is auto-generated from your collections. We maintain it so you don't have to.

You write your frontend. We handle the APIs.

Questions?

Need help with the APIs? Want to discuss your use case?

Contact us: support@restheart.com

We're developers too. We love talking about API design and implementation patterns.

---

RESTHeart Cloud: Complete data APIs for MongoDB. REST, GraphQL, WebSocket - use what fits.