https://github.com/chhedadhruv/inspirational-quotes-api
🎯 A modern, secure REST API serving 2000+ inspirational quotes with Docker support, rate limiting, and health monitoring. Built with Node.js & Express.
https://github.com/chhedadhruv/inspirational-quotes-api
api backend daily-quotes docker dotenv express health-check helmet inspiration inspirational-quotes javascript json-api motivation nodejs pagination productivity quotes rate-limiting rest-api self-improvement
Last synced: 5 days ago
JSON representation
🎯 A modern, secure REST API serving 2000+ inspirational quotes with Docker support, rate limiting, and health monitoring. Built with Node.js & Express.
- Host: GitHub
- URL: https://github.com/chhedadhruv/inspirational-quotes-api
- Owner: chhedadhruv
- License: mit
- Created: 2025-07-04T09:42:56.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-07-04T09:54:25.000Z (4 months ago)
- Last Synced: 2025-07-04T10:41:11.496Z (4 months ago)
- Topics: api, backend, daily-quotes, docker, dotenv, express, health-check, helmet, inspiration, inspirational-quotes, javascript, json-api, motivation, nodejs, pagination, productivity, quotes, rate-limiting, rest-api, self-improvement
- Language: JavaScript
- Homepage: https://quotes.dhruvchheda.com/
- Size: 0 Bytes
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📚 Quote API
*A modern, secure, and feature-rich REST API for inspirational quotes*
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://expressjs.com/)
[](https://www.docker.com/)
[](https://www.cloudflare.com/)
[Features](#-features) • [Quick Start](#-quick-start) • [API Documentation](#-api-documentation) • [Configuration](#-configuration) • [Docker](#-docker-deployment)
---
## ✨ Features
### 🎯 **Core Features**
- 🎲 Random quote generation
- 🔍 Advanced search capabilities
- 🏷️ Tag-based filtering
- 📅 Date-based queries
- 📏 Length filtering
- 👤 Author-based search
### 🛠️ **Technical Features**
- ⚙️ Environment configuration
- 🏥 Health monitoring
- 🐛 Debug mode
- 🎨 Pretty JSON responses
- 📝 Enhanced response objects
- 🔒 Security-first design
### 🚀 **Deployment**
- 🐳 Docker ready
- ☁️ Cloudflare tunnel integration
- 📊 Pagination support
- 🔄 Hot reload for development
### 🔒 **Security**
- 🛡️ Rate limiting
- 🔐 Secure headers
- 🚫 Input validation
- 🌐 CORS protection
- 🔒 Environment-based security
---
## 🚀 Quick Start
### Prerequisites
### Installation
```bash
# 1️⃣ Clone the repository
git clone
cd quote-api
# 2️⃣ Install dependencies
npm install
# 3️⃣ Set up environment variables
cp .env.example .env
# Edit .env file with your preferred settings
# 4️⃣ Start the development server
npm start
# 🎉 Your API is now running at http://localhost:3000
```
### Alternative: One-liner setup
```bash
git clone && cd quote-api && npm install && cp .env.example .env && npm start
```
---
## 🐳 Docker Deployment
🔧 Using Docker Compose (Recommended)
```bash
# Build and start services
docker-compose up -d
# View logs
docker-compose logs -f quote-api
# Stop services
docker-compose down
```
📦 Manual Docker Build
```bash
# Build the image
docker build -t quote-api .
# Run the container
docker run -p 3000:3000 --env-file .env quote-api
```
---
## 📖 API Documentation
### 🌐 Base URL
```
http://localhost:3000/api
```
> **💡 Pro Tip:** The API prefix is configurable via the `API_PREFIX` environment variable (default: `/api`)
### 📋 Endpoints Overview
Category
Endpoint
Description
Example
🎲 Random
GET /api/quote/random
Get a random quote
View
GET /api/quotes
Get all quotes (paginated)
View
🔍 Search
GET /api/quotes/search
Search quotes by content
View
GET /api/quotes/author/:name
Get quotes by author
View
GET /api/quotes/tag/:tag
Get quotes by tag
View
📊 Filter
GET /api/quotes/date/:date
Get quotes by date
View
GET /api/quotes/length
Filter by character length
View
GET /api/quote/:id
Get specific quote by ID
View
🏷️ Meta
GET /api/tags
Get all available tags
View
GET /health
Health check endpoint
View
---
### 🔍 Detailed Endpoint Documentation
#### 🎲 Random Quote
```http
GET /api/quote/random
```
📝 Response Example
```json
{
"_id": "quote-id-123",
"content": "The only way to do great work is to love what you do.",
"author": "Steve Jobs",
"tags": ["work", "passion", "success"],
"length": 49,
"dateAdded": "2023-01-01"
}
```
#### 📚 Get All Quotes
```http
GET /api/quotes?page=1&limit=10
```
**Parameters:**
- `page` (optional): Page number (default: 1)
- `limit` (optional): Number of quotes per page (default: all)
📝 Response Example
```json
{
"page": 1,
"limit": 10,
"total": 100,
"results": [
{
"_id": "quote-id-123",
"content": "Quote content here...",
"author": "Author Name",
"tags": ["tag1", "tag2"],
"length": 50,
"dateAdded": "2023-01-01"
}
]
}
```
#### 🔍 Search Quotes
```http
GET /api/quotes/search?q=success
```
**Parameters:**
- `q` (required): Search query
📝 Response Example
```json
{
"query": "success",
"total": 15,
"results": [...]
}
```
#### 👤 Quotes by Author
```http
GET /api/quotes/author/steve-jobs
```
#### 🏷️ Quotes by Tag
```http
GET /api/quotes/tag/motivation
```
#### 🆔 Get Quote by ID
```http
GET /api/quote/{id}
```
#### 📅 Quotes by Date
```http
GET /api/quotes/date/2023-01-01
```
#### 📏 Filter by Length
```http
GET /api/quotes/length?min=50&max=100
```
**Parameters:**
- `min` (optional): Minimum character length
- `max` (optional): Maximum character length
#### 🏷️ Get All Tags
```http
GET /api/tags
```
📝 Response Example
```json
{
"total": 25,
"tags": ["inspiration", "motivation", "success", "wisdom", "life"]
}
```
#### 🏥 Health Check
```http
GET /health
```
📝 Response Example
```json
{
"status": "healthy",
"timestamp": "2024-01-15T10:30:00.000Z",
"uptime": 3600,
"environment": "development",
"version": "v1"
}
```
---
## ⚙️ Configuration
### 🔧 Environment Variables
📋 View All Environment Variables
Copy the `.env.example` file to `.env` and customize the values:
```bash
cp .env.example .env
```
**Available Environment Variables:**
```env
# 🖥️ Server Configuration
PORT=3000 # Server port
NODE_ENV=development # Environment mode (development/production)
# 🔒 Rate Limiting Configuration
RATE_LIMIT_WINDOW=60000 # Rate limit window in milliseconds
RATE_LIMIT_MAX=60 # Maximum requests per window
# 🛡️ Security Headers
HELMET_ENABLED=true # Enable/disable security headers
# 🌐 CORS Configuration
CORS_ORIGIN=* # Allowed origins
CORS_METHODS=GET,POST,PUT,DELETE,OPTIONS
CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-Requested-With
# 📡 API Configuration
API_VERSION=v1 # API version for display
API_PREFIX=/api # API route prefix
# 🛠️ Development Tools
DEBUG=false # Enable debug logging
PRETTY_PRINT_JSON=true # Pretty print JSON in development
# 📊 Monitoring
HEALTH_CHECK_ENABLED=true # Enable health check endpoint
METRICS_ENABLED=false # Enable metrics collection
```
### 🔒 Security Features
**🛡️ Built-in Security**
- Rate limiting (configurable)
- Secure headers via Helmet.js
- Input validation
- CORS protection
- No information leakage
**⚙️ Configurable Security**
- Environment-based toggles
- Flexible rate limiting
- Custom CORS policies
- Debug mode controls
- Production optimizations
### 🛠️ Development Features
**🐛 Debug & Testing**
- Debug mode logging
- Pretty JSON formatting
- Environment awareness
- Hot reload support
- Health monitoring
**📊 Monitoring**
- Built-in health checks
- Process monitoring
- Environment info
- Enhanced error messages
- Rate limit headers
---
## 🌐 Cloudflare Tunnel Setup
☁️ Configure Cloudflare Tunnel
1. **Configure your tunnel in `cloudflared/config.yml`**
2. **Update `docker-compose.yml` with your tunnel ID**
3. **Deploy with Docker Compose**
```bash
docker-compose up -d
```
## 🏡 Home Server Deployment (Self-Hosting)
⚙️ Deploy from Your Home PC using Docker + Cloudflare Tunnel
### 🔧 Requirements
- Ubuntu/Linux-based home server
- Docker + Docker Compose
- Cloudflared installed and authenticated
- Cloudflare DNS set up with your domain (e.g., quotes.dhruvchheda.com)
### 📁 Folder Structure
```bash
quote-stack/
├── quote-api/ # Express API source
├── cloudflared/
│ ├── config.yml # Tunnel configuration
│ └── quote-api-tunnel.json # Tunnel credentials
└── docker-compose.yml # Service orchestration
```
### 📝 cloudflared/config.yml
```yaml
tunnel:
credentials-file: /etc/cloudflared/quote-api-tunnel.json
ingress:
- hostname:
service: http://quote-api:3000
- service: http_status:404
```
### 🚀 Deploy
```bash
docker-compose up -d
```
✅ **Your API will be available publicly at:**
https://
### 🔄 Auto-Start on Reboot (Optional)
Enable automatic startup of Docker and cloudflared on server reboot:
```bash
sudo systemctl enable docker
sudo systemctl enable cloudflared
```
---
## 📁 Project Structure
```
quote-api/
├── 📄 index.js # Main application file
├── 📊 quotes.json # Quote database
├── 🐳 Dockerfile # Docker configuration
├── 🐳 docker-compose.yml # Multi-service setup
├── 📦 package.json # Dependencies
├── 📚 README.md # Documentation
├── 🔧 .env.example # Environment variables template
├── 🔧 .env # Environment variables (local)
└── 🚫 .gitignore # Git ignore rules
```
---
## 🚀 Available Scripts
```bash
# 🎯 Production
npm start # Start the production server
# 🛠️ Development
npm run dev # Start development server with hot reload
# 🧪 Testing
npm test # Run tests (to be implemented)
```
---
## 💡 Usage Examples
🟨 JavaScript/Node.js
```javascript
// Get a random quote
const response = await fetch('http://localhost:3000/api/quote/random');
const quote = await response.json();
console.log(`"${quote.content}" - ${quote.author}`);
// Search for quotes
const searchResponse = await fetch('http://localhost:3000/api/quotes/search?q=success');
const searchResults = await searchResponse.json();
console.log(`Found ${searchResults.total} quotes about success`);
```
🐍 Python
```python
import requests
# Get a random quote
response = requests.get('http://localhost:3000/api/quote/random')
quote = response.json()
print(f'"{quote["content"]}" - {quote["author"]}')
# Get quotes by author
einstein_quotes = requests.get('http://localhost:3000/api/quotes/author/einstein')
print(f"Found {einstein_quotes.json()['total']} Einstein quotes")
```
📡 cURL
```bash
# Get a random quote
curl -X GET http://localhost:3000/api/quote/random
# Search quotes with pretty output
curl -X GET "http://localhost:3000/api/quotes/search?q=motivation" | jq
# Get health status
curl -X GET http://localhost:3000/health
```
---
## 🚀 Performance & Monitoring
**⚡ Performance**
- Fast response times
- Memory efficient
- Scalable architecture
- Docker-ready deployment
**📊 Monitoring**
- Health check endpoint
- Debug mode logging
- Rate limit headers
- Environment info
- Process monitoring
### 📈 Monitoring Commands
```bash
# View Docker logs
docker-compose logs -f
# Check health status
curl http://localhost:3000/health
# Monitor in debug mode
DEBUG=true npm start
```
---
## 🤝 Contributing
We welcome contributions! Please follow these steps:
1. **🍴 Fork** the repository
2. **🌟 Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **📝 Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **🚀 Push** to the branch (`git push origin feature/amazing-feature`)
5. **🔄 Open** a Pull Request
### 📋 Development Guidelines
- Follow existing code style
- Add tests for new features
- Update documentation
- Ensure all tests pass
- Use meaningful commit messages
---
## 📝 License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
---
## 🙏 Acknowledgments
- **Express.js** - Fast, unopinionated web framework
- **Helmet.js** - Security middleware
- **Docker** - Containerization platform
- **Cloudflare** - CDN and security services
---
### 🌟 **Star this repository if you find it helpful!**
**Built with ❤️ using Node.js and Express**
*Happy coding! 🚀*