The URL Shortener API is a web service that allows users to shorten long URLs into concise, shareable links. It supports user authentication, URL analytics, and custom short links. The backend is built using NestJS, and MongoDB is used for database storage. The API ensures security and scalability with JWT authentication and Passport.js.
-
NestJS: Backend framework for building scalable applications.
-
MongoDB: NoSQL database for storing URLs and user details.
-
Docker: Containerization for deployment. - Passport.js: Authentication middleware for handling Google OAuth.
- JWT (JSON Web Tokens): Used for user session management.
$ git clone https://github.com/your-repo/url-shortener.git
$ cd url-shortener
$ npm install
The Authentication module handles user authentication via Google Sign-In. It generates JWT tokens for session management and securely stores user details in MongoDB.
🔹 Endpoint: GET /auth/google
🔹 Description: Redirects users to Google authentication.
🔹 Response:
{
"message": "Redirecting to Google authentication"
}
🔹 Endpoint: GET /auth/google/callback
🔹 Description: Handles Google OAuth login and returns a JWT token.
🔹 Response:
{
"accessToken": "your-jwt-token",
"user": {
"email": "user@example.com",
"name": "John Doe",
"profileImage": "https://example.com/profile.jpg"
}
}
The Short URL API allows users to create and manage shortened URLs for easy sharing. It supports custom aliases, categorization, and rate limiting to prevent abuse. Each shortened URL redirects to the original long URL and includes analytics tracking for engagement insights.
POST /api/shorten
This endpoint allows users to shorten long URLs. It can optionally accept a custom alias and a topic category.
{
"longUrl": "https://example.com/very-long-url",
"customAlias": "myshortlink", // (optional)
"topic": "marketing" // (optional)
}
{
"shortUrl": "https://short.ly/myshortlink",
"createdAt": "2025-02-09T12:34:56Z"
}
GET /api/shorten
This API allows users to resolve short URLs back to their original long URLs while tracking analytics.
{
"longUrl": "https://example.com/very-long-url",
"customAlias": "myshortlink", // (optional)
"topic": "marketing" // (optional)
}
{
"shortUrl": "https://short.ly/myshortlink",
"createdAt": "2025-02-09T12:34:56Z"
}
- ✅ **Redirects users from a short URL to the original long URL**
- ✅ **Logs analytics data (timestamp, user agent, IP address, geolocation).**
The Analytics module provides insights into the performance of shortened URLs. It tracks user interactions, including total clicks, unique users, operating system and device type distribution, and engagement trends over time. This module helps users understand the reach and effectiveness of their shortened links through comprehensive analytics.
GET /api/analytics/alias/{alias}
This endpoint retrieves detailed analytics for a specific short URL, providing insights into its performance, including total clicks and unique audience interactions.
{
"totalClicks": 3,
"uniqueUsers": 2,
"clicksByDate": [
{
"_id": "2025-02-07",
"count": 1
},
{
"_id": "2025-02-08",
"count": 2
}
],
"osType": [
{
"osName": "Linux",
"uniqueClicks": 1,
"uniqueUsers": 1
},
{
"osName": "Windows 10.0",
"uniqueClicks": 2,
"uniqueUsers": 1
}
],
"deviceType": [
{
"deviceName": "mobile",
"uniqueClicks": 1,
"uniqueUsers": 1
},
{
"deviceName": "desktop",
"uniqueClicks": 2,
"uniqueUsers": 1
}
]
}
- ✅ **Retrieves total clicks and unique users for the short URL.**
- ✅ **Provides insights into operating systems and device types used**
GET /api/analytics/topic/{topic}
Retrieves analytics for all shortened URLs categorized under a specified topic. This allows users to track engagement metrics such as total clicks, unique visitors, and activity trends over time.
{ "totalClicks": 2, "uniqueUsers": 2, "clicksByDate": [ { "_id": "2025-02-08", "count": 1 }, { "_id": "2025-02-09", "count": 1 } ], "urls": [ { "shortUrl": "http://localhost:5000/api/shorten/custom-alias", "totalClicks": 2, "uniqueUsers": 2 } ] }
- ✅ **Retrieves total clicks and unique users for all short URLs under a specific topic.**
- ✅ **Provides a date-wise breakdown of clicks to analyze trends over time.**
GET /api/analytics/overall
This API retrieves overall analytics for all short URLs created by the authenticated user, offering a comprehensive view of link performance, user engagement, and device distribution.
{ "totalUrls": 4, "totalClicks": 13, "uniqueUsers": 8, "clicksByDate": [ { "_id": "2025-02-06", "count": 5 }, { "_id": "2025-02-07", "count": 3 }, { "_id": "2025-02-08", "count": 4 }, { "_id": "2025-02-09", "count": 1 } ], "osType": [ { "osName": "Windows 10.0", "uniqueClicks": 6, "uniqueUsers": 2 }, { "osName": "Linux", "uniqueClicks": 5, "uniqueUsers": 5 }, { "osName": "OS X", "uniqueClicks": 1, "uniqueUsers": 1 }, { "osName": "unknown", "uniqueClicks": 1, "uniqueUsers": 1 } ], "deviceType": [ { "deviceName": "desktop", "uniqueClicks": 7, "uniqueUsers": 3 }, { "deviceName": "mobile", "uniqueClicks": 6, "uniqueUsers": 6 } ] }
- ✅ **Retrieves the total number of short URLs created by the user.**
- ✅ **Provides total clicks and unique user interactions across all URLs.**
To prevent abuse, rate limiting is implemented. A user can create a limited number of short URLs within a given time frame.
- ✅ **Max Requests:** 5 per minute per user.
- ✅ **Error Response:** If a user exceeds the limit, they receive a 429 status.
{
"statusCode": 429,
"message": "Too many requests. Try again later."
}
Create a .env file and configure:
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-secret
JWT_SECRET=your-jwt-secret
MONGO_URI=your-mongodb-url
# Start the server in development mode
$ npm run start:dev
If you want to run the application inside a Docker container:
# Build the Docker image
$ docker build -t url-shortener-api .
Run the container
$ docker run -p 5000:5000 --env-file .env url-shortener-api
🧪 Testing the Deployed API
The API is currently deployed on Amazon EC2 and can be accessed at:
http://your-ip:5000/api/