RESTHeart Cloud is coming soon! Stay tuned!

v8 v7 v6 v5 v4 v3
Edit Page

Getting Started with RESTHeart Cloud

Get your backend running in under 5 minutes! This guide will walk you through creating your first API instance and demonstrate how RESTHeart Cloud accelerates development. Each API instance provides a single database with collections that you’ll create to build your application.

Prerequisites

  • A web browser

  • An email address

  • Optional: curl, Postman, or any HTTP client for testing

Step 1: Sign Up

  1. Navigate to https://cloud.restheart.com

  2. Click "Sign Up" or "Create Account"

  3. Enter your email address and create a strong password

  4. Verify your email address through the confirmation link

Step 2: Create Your First API Instance

  1. Log in to your RESTHeart Cloud dashboard

  2. Click "Create New API"

  3. Choose your desired plan:

    • Free: Perfect for learning and prototyping

    • Shared: For small to medium applications

    • Dedicated: Production-ready with dedicated resources

  4. Select a geographical region (e.g., EU Central, US East)

  5. Provide an optional name for your API instance

  6. Click "Create"

⏱️ Your API will be ready in seconds!

Your API instance gets a unique endpoint: [instanceid].[region]-[tier].restheart.com

Example: f2d222.eu-central-1-free-1.restheart.com

Understanding API Instances

Each API instance in RESTHeart Cloud provides:

  • One Database: The root URL (/) represents your single database

  • One User Base: The /users collection stores all authentication information

  • One ACL Set: The /acl collection defines all permissions

  • Isolated Environment: Complete separation from other instances

Important
 Create separate API instances for separate applications. If you’re building multiple applications, don’t try to share a single API instance between them. Each application should have its own API instance with its own users, permissions, and data collections.

Step 3: Obtain Temporary JWT Token

  1. In the API instance dashboard

  2. Navigate to the "Security" or "Setup" section

  3. Click "Generate Setup Token"

  4. Copy the generated JWT token securely

Warning
 This token has administrative privileges and expires quickly. Use it only for initial setup.

Step 4: Create Your First Collections

Unlike traditional databases where you need to create a database first, in RESTHeart Cloud:

  • Each API instance already has a single database at the root path (/)

  • You only need to create collections directly under the root

  • Each application should have its own API instance

Let’s create collections for a simple task management system:

# Create a 'tasks' collection in your database
curl -X PUT https://[your-instance].restheart.com/tasks \
     -H "Authorization: Bearer [your-temporary-token]"

# Create a 'categories' collection
curl -X PUT https://[your-instance].restheart.com/categories \
     -H "Authorization: Bearer [your-temporary-token]"

🎉 That’s it! You now have fully functional collections with REST endpoints in your database.

Step 5: Add Your First Task

Insert a task document:

curl -X POST https://[your-instance].restheart.com/tasks \
     -H "Authorization: Bearer [your-temporary-token]" \
     -H "Content-Type: application/json" \
     -d '{
         "title": "Learn RESTHeart Cloud",
         "description": "Complete the getting started tutorial",
         "status": "in-progress",
         "priority": "high",
         "createdAt": "2024-01-15T10:00:00Z"
     }'

Step 5.1: Query Your Data

RESTHeart automatically provides powerful querying capabilities:

# Get all tasks
curl -H "Authorization: Bearer [your-temporary-token]" \
     https://[your-instance].restheart.com/tasks

# Get high-priority tasks only
curl -H "Authorization: Bearer [your-temporary-token]" \
     "https://[your-instance].restheart.com/tasks?filter={'priority':'high'}"

# Get tasks sorted by creation date
curl -H "Authorization: Bearer [your-temporary-token]" \
     "https://[your-instance].restheart.com/tasks?sort={'createdAt':-1}"

Step 6: Set Up User Authentication

Each API instance has its own user management system in the reserved /users collection:

# Create a task manager user
curl -X POST https://[your-instance].restheart.com/users \
     -H "Authorization: Bearer [your-temporary-token]" \
     -H "Content-Type: application/json" \
     -d '{
         "_id": "taskmanager",
         "password": "SecurePassword123!",
         "email": "manager@company.com",
         "roles": ["task-manager"]
     }'

# Create a regular user
curl -X POST https://[your-instance].restheart.com/users \
     -H "Authorization: Bearer [your-temporary-token]" \
     -H "Content-Type: application/json" \
     -d '{
         "_id": "developer",
         "password": "AnotherSecurePass456!",
         "email": "dev@company.com",
         "roles": ["task-user"]
     }'

Step 7: Configure Permissions

Set up role-based access control using the reserved /acl collection:

# Task managers can do everything
curl -X POST https://[your-instance].restheart.com/acl \
     -H "Authorization: Bearer [your-temporary-token]" \
     -H "Content-Type: application/json" \
     -d '{
         "_id": "task-manager-full-access",
         "roles": ["task-manager"],
         "predicate": "path-prefix[\"/tasks\"]",
         "priority": 100
     }'

# Regular users can only read and create tasks
curl -X POST https://[your-instance].restheart.com/acl \
     -H "Authorization: Bearer [your-temporary-token]" \
     -H "Content-Type: application/json" \
     -d '{
         "_id": "task-user-limited-access",
         "roles": ["task-user"],
         "predicate": "path-prefix[\"/tasks\"] and (method[GET] or method[POST])",
         "priority": 100
     }'

Step 8: Test User Authentication

Now test with your newly created users:

# Login as taskmanager (full access)
curl -X GET https://[your-instance].restheart.com/tasks \
     -u taskmanager:SecurePassword123!

# Login as developer (limited access)
curl -X GET https://[your-instance].restheart.com/tasks \
     -u developer:AnotherSecurePass456!

🚀 What You’ve Accomplished

In just a few minutes, you’ve built a complete backend with:

  • ✅ API Instance: Your own dedicated RESTHeart environment

  • ✅ Collections: Ready to store your application data

  • ✅ REST API: Full CRUD operations with advanced querying

  • ✅ User Management: Secure authentication system via /users

  • ✅ Access Control: Role-based permissions via /acl

  • ✅ Production-Ready: HTTPS, encrypted data, monitoring

When to Create Another API Instance

Create separate API instances for:

  • Different Applications: Each application should have its own API instance

  • Separate Environments: Development, staging, and production

  • Client Projects: Separate instances for different clients

  • Isolation Requirements: When you need separate user bases or permissions

Each API instance provides: * Single database at root path (/) * Dedicated user management (/users collection) * Dedicated permission system (/acl collection) * Separate monitoring and usage metrics

Next Level: Real-Time Features

Add WebSocket support for real-time task updates:

# Create a change stream for real-time updates
curl -X POST https://[your-instance].restheart.com/_streams/task-updates \
     -H "Authorization: Bearer [your-temporary-token]" \
     -H "Content-Type: application/json" \
     -d '{
         "uri": "ws://[your-instance].restheart.com/_streams/task-updates",
         "stages": [
             {"$match": {"ns.coll": "tasks"}},
             {"$project": {"_id": 1, "operationType": 1, "fullDocument": 1}}
         ]
     }'

Now any changes to tasks will be broadcast in real-time to connected WebSocket clients!

Best Practices for Production

  • Security: Rotate tokens regularly and use strong passwords

  • Performance: Implement proper indexing for frequently queried fields

  • Monitoring: Use the dashboard to track API usage and performance

  • Backup: Enable automatic backups for production data

  • Scaling: Start with Free/Shared and upgrade to Dedicated as you grow

Real-World Integration Examples

Web Application

// Frontend JavaScript example
const response = await fetch('https://[your-instance].restheart.com/tasks', {
    method: 'POST',
    headers: {
        'Authorization': 'Basic ' + btoa('taskmanager:SecurePassword123!'),
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        title: 'New feature development',
        status: 'todo',
        assignee: 'john@company.com'
    })
});

Mobile App (React Native)

// React Native example
const createTask = async (task) => {
    const response = await fetch('https://[your-instance].restheart.com/tasks', {
        method: 'POST',
        headers: {
            'Authorization': 'Basic ' + base64.encode('developer:AnotherSecurePass456!'),
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(task)
    });
    return response.json();
};

Troubleshooting

Common Issues

  • Token Expired: Generate a new temporary token from the dashboard

  • CORS Issues: Configure CORS settings in your API instance settings

  • Permission Denied: Check user roles and ACL permissions

  • Connection Problems: Verify your instance URL and network connectivity

Performance Tips

  • Use query filters to limit returned data

  • Implement pagination for large datasets

  • Create indexes for frequently queried fields

  • Use aggregation pipelines for complex data processing

Getting Help

Next Steps

🎯 Immediate Actions

  • Explore Your Dashboard: Monitor API usage, manage users, view logs

  • Try GraphQL: Create GraphQL schemas for type-safe queries

  • Set Up Webhooks: Configure notifications for data changes

  • Custom Domains: Add your own domain (Shared/Dedicated tiers)

📚 Deep Dive Learning

🏗️ Production Deployment

  • Upgrade Your Plan: Scale from Free to Shared or Dedicated

  • Environment Strategy: Set up staging and production instances

  • Monitoring & Alerts: Configure performance monitoring

  • Backup Strategy: Implement data backup and recovery plans

💡 Inspiration

Check out example applications built with RESTHeart Cloud: * Task Management System (what you just built!) * E-commerce Backend * IoT Data Collection Platform * Content Management System * Real-time Chat Application

Start building your next application with RESTHeart Cloud today! 🚀