Getting Started with CalmAPI

Learn how to install CalmAPI and create your first project in minutes.

Prerequisites#

Before you begin, make sure you have:

Node.js (v14 or higher) - Download here
MongoDB - Download here or use MongoDB Atlas (free cloud database)
Basic JavaScript knowledge
A code editor (VS Code recommended)

Installation#

Step 1: Install CalmAPI CLI Globally#

Open your terminal and run:

Shell

npm install -g calmapi

This installs the CalmAPI command-line tool globally on your system.

Step 2: Verify Installation#

Check if it's installed correctly:

Shell

calmapi --version

You should see the version number (e.g., 0.2.5).

Creating Your First Project#

Step 1: Run CalmAPI Generator#

Navigate to your workspace directory and run:

Shell

cd ~/projects
calmapi

Step 2: Follow the Setup Wizard#

The interactive wizard will ask you:

? Project name: my-awesome-api
? Description: My first REST API with CalmAPI
? Author: Your Name
? Database name: my_awesome_api
? Port (default 3000): 3000

Pro Tip: Use kebab-case for project names (e.g., my-awesome-api)

Step 3: Navigate to Your Project#

Shell

cd my-awesome-api

Step 4: Install Dependencies#

Shell

npm install

Configuration#

Environment Variables#

CalmAPI uses a .env file for configuration. Open it and configure:

Shell

# Server Configuration
PORT=3000
NODE_ENV=development

# Database Configuration
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/my_awesome_api

# JWT Secret (Change this!)
JWT_SECRET=your-super-secret-key-change-this-in-production

# AWS S3 (Optional - for file uploads)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_S3_BUCKET=your-bucket-name
AWS_REGION=us-east-1

🔒 Security Note: Never commit .env to version control! It's already in .gitignore.

Project Structure#

After setup, your project looks like this:

my-awesome-api/
├── node_modules/          # Dependencies
├── src/                   # Your application code
│   ├── configs/           # App configurations
│   ├── helpers/           # Helper functions
│   ├── modules/           # API modules (this is where you work!)
│   │   ├── auth/          # Authentication module
│   │   ├── user/          # User module
│   │   ├── media/         # File upload module
│   │   └── post/          # Sample CRUD module
│   ├── plugins/           # Custom plugins
│   └── utils/             # Utility functions
├── system/                # CalmAPI core (don't edit)
│   ├── configs/           # Server, database, routing
│   ├── core/              # Base classes
│   └── helpers/           # System helpers
├── .env                   # Environment variables
├── .gitignore             # Git ignore rules
├── calmapi.json           # CalmAPI metadata
├── index.js               # Application entry point
├── package.json           # Project dependencies
└── eslintrc.json          # ESLint configuration

Key Directories#

src/modules/ - This is where YOU create APIs. Each folder is a module.
system/ - CalmAPI's core code. You can read it, admire it, maybe send it a compliment. But modifying it? That's "I know what I'm doing" territory, and if you're reading this documentation, statistically speaking...
.env - Your configuration. Keep it secret!

Running Your Application#

Start the Server#

Shell

npm start

You should see:

⬤  CALMAPI - Keep Calm and REST

✔ Project: my-awesome-api v1.0.0
✔ CalmAPI Version: 0.2.5
✔ Application Started
✔ Connected to Database: my_awesome_api
✔ Listening on port 3000
✔ Endpoint Base URL: http://127.0.0.1:3000

┌─────────┬─────────────────┬────────┬──────────────┐
│ Module  │ Route           │ Mapped │ API Exposed  │
├─────────┼─────────────────┼────────┼──────────────┤
│ auth    │ /auth           │ ✔      │ ✔            │
│ user    │ /users          │ -      │ ✘            │
│ media   │ /media          │ ✔      │ ✔            │
│ post    │ /posts          │ ✔      │ ✔            │
└─────────┴─────────────────┴────────┴──────────────┘

✔ API Modules Loaded

🎉 Congratulations! Your API is running!

Testing Your API#

Method 1: Browser#

Open your browser and visit:

http://localhost:3000

You should see:

JSON

{
  "status": true,
  "message": "Welcome to the my-awesome-api"
}

Method 2: Using curl#

In your terminal:

Shell

curl http://localhost:3000/api

Response:

JSON

{
  "status": true,
  "data": {
    "message": "API Running"
  }
}

Method 3: Using Postman or Insomnia#

Download Postman or Insomnia
Create a new request
Set URL to http://localhost:3000/api/posts
Click Send

Understanding Built-in Modules#

CalmAPI comes with 4 pre-built modules:

1. Auth Module (`/api/auth`)#

Handles user authentication:

Register new users
Login/logout
Password reset
JWT token management

2. User Module (`/api/users`)#

User data model (not exposed by default)

3. Media Module (`/api/media`)#

File uploads to AWS S3

4. Post Module (`/api/posts`)#

A complete example CRUD module showing best practices

Your First API Test#

Let's test the Post module that comes with CalmAPI:

1. Register a User#

Shell

curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "securepass123"
  }'

Response:

JSON

{
  "status": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "_id": "60d5ec49f1b2c72b8c8e4f3a",
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Save the token! You'll need it for authenticated requests.

2. Create a Post (Authenticated)#

Shell

curl -X POST http://localhost:3000/api/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "title": "My First Post",
    "content": "Hello CalmAPI!"
  }'

3. Get All Posts#

Shell

curl http://localhost:3000/api/posts

Common Issues & Solutions#

Issue: "Cannot connect to database"#

Solution: Make sure MongoDB is running:

Shell

# Check if MongoDB is running
ps aux | grep mongod

# Start MongoDB (if installed locally)
brew services start mongodb-community  # macOS
sudo systemctl start mongod            # Linux

Or use MongoDB Atlas cloud database.

Issue: "Port 3000 is already in use"#

Solution: Either:

Stop the process using port 3000
Change PORT in .env to another port (e.g., 3001)

Issue: "Module not found"#

Solution: Make sure you ran npm install in your project directory.

Development Tips#

1. Hot Reload (Optional – Use with Caution)#

You can install nodemon for automatic restarts during development:

Shell

npm install -g nodemon

Then run:

Shell

nodemon index.js

⚠️ Why we don't recommend nodemon for database-heavy projects:

Automatic restarts on file save can cause subtle, hard-to-debug issues, especially when working with database schemas. For example, if you modify a Mongoose model's index configuration, nodemon may restart the server mid-change and apply a partial or unintended index to your database. When you save again with the correct configuration, the damage is already done, but there's no obvious error, leaving you chasing a phantom bug.

Safer alternatives:

Run your server manually with npm start or node index.js and restart only when needed

Use nodemon selectively by ignoring database model files: nodemon --ignore 'models/'

2. ESLint#

Check your code quality:

Shell

npm run lint

3. Keep Your Token Safe#

When testing, save your auth token in a variable:

Shell

# In your terminal
export TOKEN="your-jwt-token-here"

# Then use it
curl -H "Authorization: Bearer $TOKEN" http://localhost:3000/api/posts

What's Next?#

Now that your project is running, let's understand how it works!

Next: Understanding the Architecture →

Quick Reference#

Shell

# Install CalmAPI
npm install -g calmapi

# Create new project
calmapi

# Generate a module
calmapi generate module product

# Start server
npm start

# Run linter
npm run lint

Getting Started with CalmAPI

Prerequisites#

Installation#

Step 1: Install CalmAPI CLI Globally#

Step 2: Verify Installation#

Creating Your First Project#

Step 1: Run CalmAPI Generator#

Step 2: Follow the Setup Wizard#

Step 3: Navigate to Your Project#

Step 4: Install Dependencies#

Configuration#

Environment Variables#

Project Structure#

Key Directories#

Running Your Application#

Start the Server#

Testing Your API#

Method 1: Browser#

Method 2: Using curl#

Method 3: Using Postman or Insomnia#

Understanding Built-in Modules#

1. Auth Module (/api/auth)#

2. User Module (/api/users)#

3. Media Module (/api/media)#

4. Post Module (/api/posts)#

Your First API Test#

1. Register a User#

2. Create a Post (Authenticated)#

3. Get All Posts#

Common Issues & Solutions#

Issue: "Cannot connect to database"#

Issue: "Port 3000 is already in use"#

Issue: "Module not found"#

Development Tips#

1. Hot Reload (Optional – Use with Caution)#

2. ESLint#

3. Keep Your Token Safe#

What's Next?#

Quick Reference#

1. Auth Module (`/api/auth`)#

2. User Module (`/api/users`)#

3. Media Module (`/api/media`)#

4. Post Module (`/api/posts`)#