Hoppscotch: The Open-Source API Development Platform Complete Guide

Have you ever found yourself frustrated by the rising costs and feature lock-in of commercial API testing tools? If you're a developer who spends hours every day testing REST and GraphQL endpoints, you've probably wondered: isn't there a better, lighter, and—ideally—free alternative? Meet Hoppscotch, the open-source API development platform that's here to challenge the status quo.

1. What Is Hoppscotch?

Hoppscotch (formerly known as Postwoman) is a lightweight, open-source API development ecosystem designed to be a genuine free alternative to Postman. Its core value proposition is built on four pillars: completely free, no login required, built for collaboration, and fully self-hostable.

Problems It Solves

Postman has become heavily commercialized, with advanced features locked behind paywalls
API testing tools are often bloated, with steep learning curves
Team collaboration features typically require paid subscriptions
Data security and privacy concerns with cloud-hosted solutions

Ideal Use Cases

Backend developers testing REST/GraphQL APIs
Frontend developers debugging API integrations
Teams collaboratively managing API collections
Enterprise intranet API management

2. Technical Architecture

Tech Stack

Frontend: Vue 3 + TypeScript + Tailwind CSS
Backend: Node.js + Express (optional)
Database: Firebase / PostgreSQL
Real-time Communication: WebSocket
Deployment: Docker + Kubernetes

Architecture Highlights

1. Frontend-first design with offline support (PWA)
2. Optional backend for team collaboration
3. Plugin-based architecture for extensibility
4. Multiple authentication methods supported

Core Module Overview

┌──────────────────────────────────────┐
│         Hoppscotch UI                │
├──────────────────────────────────────┤
│  REST  │  GraphQL  │  WebSocket      │
├──────────────────────────────────────┤
│  Collections  │  Env Variables  │  Team  │
└──────────────────────────────────────┘

3. Core Features

REST API Testing

Supported HTTP Methods:

// Supported HTTP methods GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

// Request example GET https://api.example.com/users Authorization: Bearer {token} Content-Type: application/json

Request Parameters:

# Query parameters

?limit=10&offset=0

Path parameters
/users/:id

Header
Authorization: Bearer token
Content-Type: application/json

Body
{
  "name": "John",
  "email": "[email protected]"
}

Authentication Methods:

# Supported

None
Basic Auth
Bearer Token
OAuth 2.0
API Key

GraphQL Support

Query Example:

query {

  user(id: 1) {

    name

    email

    posts {

      title

      content

    }

  }

}

Variables:

{

  "id": 1

}

Schema Auto-completion:

# Auto-fetches schema

Supports type hints


Real-time syntax validation

WebSocket Testing

Connection Management:

// Connect ws://localhost:8080/socket // Send message {"action": "subscribe", "channel": "updates"}

// Receive messages // Real-time display of server push

Environment Variables

Environment Configuration:

{

  "base_url": "https://api.example.com",

  "token": "your-token-here",

  "user_id": 123

}

Using Variables:

GET {{base_url}}/users/{{user_id}}

Authorization: Bearer {{token}}

Environment Switching:

- Development

Staging
Production
Custom environments

Collection Management

Organization Structure:

📁 Project A

  ├── 📁 User Module

  │   ├── 📄 Get User List

  │   ├── 📄 Create User

  │   └── 📄 Update User

  ├── 📁 Order Module

  │   ├── 📄 Create Order

  │   └── 📄 Query Order

  └── 📁 Payment Module

Collection Features:

- Folder nesting

Drag-and-drop reordering
Bulk operations
Import/export
Version history

Test Scripts

// Pre-request script
pw.env.set("timestamp", Date.now())

// Post-response tests

pw.test("Status code is 200", () => {

  pw.expect(pw.response.status).toBe(200)

})

pw.test("Response has user data", () => {

  const body = pw.response.body

  pw.expect(body).toHaveProperty("id")

  pw.expect(body).toHaveProperty("name")

})

// Extract data

const userId = pw.response.body.id

pw.env.set("userId", userId)

4. Deployment Guide

Option 1: Use the Hosted Version (Simplest)

# Visit the official online version
https://hoppscotch.io

Advantages
No installation required
No registration needed
Data stored in browser
Offline support (PWA)

Option 2: Docker Deployment

Quick Start:

# Pull image

docker pull hoppscotch/hoppscotch:latest

Run container
docker run -d \
  --name hoppscotch \
  -p 3000:3000 \
  hoppscotch/hoppscotch:latest

Access
http://localhost:3000

Docker Compose (Recommended):

# docker-compose.yml version: "3.8" services: hoppscotch: image: hoppscotch/hoppscotch:latest container_name: hoppscotch ports: - "3000:3000" environment: - BASE_URL=http://localhost:3000 - ENABLE_ANALYTICS=false volumes: - ./data:/app/data restart: unless-stopped # Optional: PostgreSQL backend postgres: image: postgres:15 container_name: hoppscotch-db environment: - POSTGRES_USER=hoppscotch - POSTGRES_PASSWORD=secret - POSTGRES_DB=hoppscotch volumes: - postgres_data:/var/lib/postgresql/data restart: unless-stopped # Optional: Backend service backend: image: hoppscotch/backend:latest container_name: hoppscotch-backend ports: - "3170:3170" environment: - DATABASE_URL=postgresql://hoppscotch:secret@postgres:5432/hoppscotch - JWT_SECRET=your-secret-key depends_on: - postgres restart: unless-stopped

volumes: postgres_data:

Start the Service:

# Create directory

mkdir -p hoppscotch

cd hoppscotch

Create config file
vim docker-compose.yml

Start
docker-compose up -d

View logs
docker-compose logs -f

Access
http://localhost:3000

Option 3: Build from Source

1. Clone the Repository

git clone https://github.com/hoppscotch/hoppscotch.git

cd hoppscotch

2. Install Dependencies

# Install Node.js 18+

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

sudo apt install nodejs

Install pnpm
npm install -g pnpm

Install project dependencies
pnpm install

3. Configure Environment Variables

# Copy example config

cp .env.example .env

Edit config
vim .env

Key configuration
VITE_BASE_URL=http://localhost:3000
VITE_BACKEND_URL=http://localhost:3170
VITE_ENABLE_ANALYTICS=false

4. Build and Run

# Development mode

pnpm dev

Production build
pnpm build

Run production version
pnpm start

Option 4: Kubernetes Deployment

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hoppscotch
spec:
  replicas: 3
  selector:
    matchLabels:
      app: hoppscotch
  template:
    metadata:
      labels:
        app: hoppscotch
    spec:
      containers:
      - name: hoppscotch
        image: hoppscotch/hoppscotch:latest
        ports:
        - containerPort: 3000
        env:
        - name: BASE_URL
          value: "https://api.yourdomain.com"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"


apiVersion: v1
kind: Service
metadata:
  name: hoppscotch-service
spec:
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 3000
  selector:
    app: hoppscotch


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hoppscotch-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts:
    - api.yourdomain.com
    secretName: hoppscotch-tls
  rules:
  - host: api.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: hoppscotch-service
            port:
              number: 80

# Deploy
kubectl apply -f deployment.yaml

Check status
kubectl get pods -l app=hoppscotch

View logs
kubectl logs -f deployment/hoppscotch

5. Comparison with Alternatives

| Feature | Hoppscotch | Postman | Insomnia | Bruno |
|---------|-----------|---------|----------|-------|
| Price | Free | Freemium | Freemium | Free |
| Open Source | Yes | No | No | Yes |
| Self-hosted | Yes | No | No | Yes |
| Team Collaboration | Yes (self-hosted) | Paid | Paid | Git-based |
| GraphQL Support | Yes | Yes | Yes | Yes |
| WebSocket | Yes | Yes | No | No |
| Offline (PWA) | Yes | No | Yes | Yes |
| Browser-based | Yes | Yes | No | No |
| Plugin System | Yes | Yes | Limited | No |
| Test Scripts | Yes | Yes | Yes | Yes |

6. Common Issues & Troubleshooting

Issue 1: Cannot Connect to Backend

# Troubleshooting steps 1. Check backend service docker-compose ps docker logs hoppscotch-backend 2. Check network connectivity curl http://localhost:3170/health 3. Check firewall rules sudo ufw allow 3170

4. Verify environment variables Ensure VITE_BACKEND_URL is correct

Issue 2: Data Loss After Browser Refresh

# Prevention measures 1. Use the backend service - Data persistence - Auto sync 2. Export regularly - Export collections - Back up data

3. Use version control - Git integration - Version history

Issue 3: Performance Degradation with Large Collections

# Optimization steps 1. Clear cache - Browser cache - LocalStorage 2. Reduce collection size - Split large collections - Delete unused requests

3. Upgrade hardware - Increase memory - Use SSD

7. FAQ

Q: Is Hoppscotch really 100% free?
A: Yes. Hoppscotch is fully open-source under the MIT license. All features, including team collaboration (when self-hosted), are free with no hidden costs.

Q: Can I use Hoppscotch offline?
A: Absolutely. Hoppscotch is a PWA (Progressive Web App), so you can install it on your device and use it without an internet connection. Data is stored locally in your browser.

Q: How does Hoppscotch compare to Postman for team collaboration?
A: While Postman charges for team features, Hoppscotch offers real-time collaboration, conflict resolution, and version history when you self-host the backend—all for free.

Q: Does Hoppscotch support automated testing in CI/CD pipelines?
A: Yes. You can use Hoppscotch's CLI tool or run collections via the API, making it easy to integrate API testing into your CI/CD workflows.

Q: Can I import my existing Postman collections?
A: Yes, Hoppscotch supports importing Postman collection files (JSON format). Simply use the import feature in the collections panel.

Q: Is Hoppscotch suitable for enterprise use?
A: For small to medium teams, Hoppscotch is excellent. For large enterprises requiring SSO, audit logs, and enterprise-grade support, you may need to evaluate your specific compliance requirements.

8. Who Should Use This?

Ideal For:

Individual developers seeking a free, powerful API tool
Small to medium teams wanting collaboration without subscription fees
Projects with limited budgets
Teams that value open-source and data privacy
Developers who need a lightweight, browser-based solution

Not Ideal For:

Organizations requiring enterprise-level SLA and support
Teams needing advanced mock services with complex logic
Large-scale API gateway management
Environments with strict SSO and compliance mandates

Verdict

Hoppscotch is a powerful, completely free API development tool that delivers the core functionality of Postman while maintaining the advantages of being open-source. Its PWA-based architecture means it runs everywhere, and the optional self-hosted backend enables full team collaboration without any licensing costs. If you're tired of paywalls and bloated tools, Hoppscotch is worth every minute of your time.

GitHub Repository: https://github.com/hoppscotch/hoppscotch

Hoppscotch: The Open-Source API Development Platform Complete Guide

1. What Is Hoppscotch?

Problems It Solves

Ideal Use Cases

2. Technical Architecture

Tech Stack

Architecture Highlights

Core Module Overview

3. Core Features

REST API Testing

Path parameters

Header

Body

GraphQL Support

Supports type hints

Real-time syntax validation

WebSocket Testing

Environment Variables

Collection Management

Test Scripts

4. Deployment Guide

Option 1: Use the Hosted Version (Simplest)

Advantages

Option 2: Docker Deployment

Run container

Access

Create config file

Start

View logs

Access

Option 3: Build from Source

Install pnpm

Install project dependencies

Edit config

Key configuration

Production build

Run production version