🔗 Shortify - URL Shortener API

📚 Contents

📖 Overview | ⚙️ Prerequisites | 🛠 Tech Stack | 📊 Features | 🔌 API Endpoints | 🔐 Authentication Setup | ⚙️ Environment Variables | 🚀 Installation | 🧪 Testing | 📚 API Documentation

📖 Overview

Shortify is a powerful URL shortening service built with scalability and analytics in mind. It provides advanced features including topic-based organization, detailed analytics, and Google Sign-In authentication, making it perfect for both personal and enterprise use.

🌐 Live Endpoints

• Authentication Endpoint: https://shortify.avm-ayurvedic.online/api/auth/google
• API Documentation: Postman Documentation

🛠 Tech Stack

• Backend: Node.js with Express
• Database: MongoDB with Mongoose
• Caching: Redis
• Authentication: Passport.js with Google OAuth 2.0
• Testing: Jest
• Analytics: Custom implementation with geolocation tracking

⚙️ Prerequisites

Before running the application, ensure you have:

• Node.js 22.x or higher
• Redis Server
• MongoDB
• Yarn package manager
• Google Cloud Console account

📊 Features

1. User Authentication

• Google Sign-In integration
• Secure session management
• JWT token-based authentication
• HTTP-only cookie implementation

2. URL Shortening

• Custom alias support
• Topic-based organization
• Automatic URL validation
• Collision detection
• Rate limiting protection

3. Advanced Analytics

• Click Tracking

  • Total clicks
  • Unique visitors
  • Geographic distribution
  • Time-based analytics

• Device Analytics

  • Operating system tracking
  • Device type detection
  • Browser statistics
  • Screen resolution data

• Topic-Based Insights

  • Category-wise performance
  • Comparative analytics
  • Trend analysis
  • Engagement metrics

4. Performance Features

• Redis caching
• Load balancing ready
• Rate limiting
• Response compression

5. Security Measures

• URL sanitization
• XSS protection
• Rate limiting
• CORS configuration
• Input validation

🔌 API Endpoints

Authentication

GET /api/auth/google
GET /api/auth/callback

URL Management

POST /api/shorten
{
  "longUrl": "https://example.com",
  "customAlias": "my-link",
  "topic": "acquisition"
}

GET /api/shorten/:alias

Analytics

GET /api/analytics/alias/:alias
GET /api/analytics/topic/:topic
GET /api/analytics/overall

🔐 Authentication Setup

Google OAuth Configuration

1. Create Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project
   • Enable Google+ API and OAuth API

2. Configure OAuth Consent Screen:

   • Set application name
   • Add authorized domains
   • Configure scopes (email, profile)

3. Get OAuth Credentials:

   • Create OAuth Client ID
   • Configure redirect URIs
   • Save Client ID and Secret

⚙️ Environment Variables

# Environment Configuration
NODE_ENV=development
MONGO_URI=mongodb://localhost:27017/Shortify
CLIENT_URL=http://localhost:3000
PORT=8000

# Redis Configuration
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# Security
TOKEN_SECRET=your_jwt_secret_key

# External Services
GEOLOCATION_PROVIDER=http://ip-api.com/json/

# URLs
SERVER_URL=http://localhost:8000

# Google OAuth
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

🚀 Installation

1. Clone the repository:

git clone https://github.com/sinanptm/shortify.git
cd shortify

2. Install dependencies:

yarn install

3. Set up environment:

cp .env.example .env

4. Start development server:

yarn dev

🧪 Testing

Run the test suite:

yarn test

📚 API Documentation

For detailed API documentation and examples, visit our Postman Documentation.