Skip to main content

​
Welcome to Short-URL API

Short-URL is a comprehensive URL shortener and management API built with FastAPI. It goes beyond simple URL shortening by providing advanced features like password protection, JWT authentication, hit tracking, and complete URL lifecycle management.

​
What is Short-URL?

Short-URL is a production-ready API service that allows you to:
  • Create short URLs with custom aliases
  • Protect URLs with optional password authentication
  • Manage URLs through a complete set of authenticated endpoints
  • Track usage with built-in hit counters and analytics
  • Control access by pausing and resuming URLs on demand

​
Key Features

JWT Authentication

Secure token-based authentication using Bearer tokens for all management operations

Password Protection

Optional password protection for URLs with secure password hashing using PBKDF2-SHA256

URL Management

Complete control over your URLs - change destinations, pause/resume, delete, and reset hit counters

Hit Tracking

Built-in analytics to track how many times your short URLs are accessed

MongoDB Backend

Asynchronous MongoDB integration with Motor for high-performance data operations

CORS Support

Configurable CORS middleware for cross-origin requests

​
Architecture Overview

Short-URL is built on a modern Python stack:

​
Core Technologies

  • FastAPI - High-performance web framework with automatic API documentation
  • Motor - Asynchronous MongoDB driver for Python
  • Pydantic - Data validation and settings management using Python type annotations
  • Python-JOSE - JWT token creation and verification
  • Passlib - Secure password hashing with PBKDF2-SHA256

​
Database Structure

The API uses MongoDB with two main collections:
  • URLMap - Stores URL mappings with unique codes and passwords
  • URLStats - Tracks hit counts, creation dates, and active states

​
Security Features

All management endpoints require JWT authentication. Passwords are hashed using PBKDF2-SHA256, never stored in plain text.
  • Bearer token authentication for protected endpoints
  • Password validation (3-20 characters)
  • URL blacklist support to prevent malicious links
  • Reserved keyword protection for url_code values

​
API Endpoints Overview

The API provides two categories of endpoints:

​
Public Endpoints

  • POST /create - Create new short URLs
  • POST /login - Authenticate and receive access tokens
  • GET /{url_code} - Redirect to destination URL
  • GET /health - Database health check

​
Protected Endpoints (Require Authentication)

  • DELETE /delete - Delete a URL
  • PATCH /pause - Temporarily disable a URL
  • PATCH /resume - Re-enable a paused URL
  • PATCH /change_url - Update the destination URL
  • PATCH /reset_hits - Reset the hit counter
  • POST /change_password - Update URL password
  • GET /details - Retrieve URL statistics
  • GET /validate_token - Verify token validity
  • GET /refresh_token - Get a new access token

​
What Problems Does It Solve?

Unlike simple URL shorteners, Short-URL provides complete lifecycle management. You can update destinations, pause URLs temporarily, track usage, and delete URLs when no longer needed - all without losing your short codes.
Password protection ensures that only authorized users can access your shortened URLs. Combined with JWT authentication for management, your URLs are protected at both the access and administrative levels.
Built-in hit tracking lets you monitor how often your URLs are accessed. Perfect for marketing campaigns, content distribution, or understanding user engagement.
Built with FastAPI and async MongoDB, the API can handle high-traffic scenarios with horizontal scaling. CORS support enables integration with any frontend application.

​
Getting Started

Quickstart Guide

Get up and running in 5 minutes with our step-by-step guide

Installation

Detailed installation instructions and environment setup

API Reference

Complete API endpoint documentation with examples

Authentication

Learn how to authenticate and manage access tokens

​
Interactive Documentation

Once you have the server running, FastAPI provides automatic interactive documentation:
  • Swagger UI - Available at /docs
  • ReDoc - Available at /redoc
Both interfaces let you test endpoints directly from your browser.
Start with the Quickstart Guide to create your first short URL in minutes!

Build docs developers (and LLMs) love

Get started for freeTalk to us