Skip to Content
Quick Start Guide

Source: Jolli-sample-repos/url-shortener  Last Updated: 4/8/2026

Quick Start Guide

Get up and running with the URL Shortener in minutes. This guide will show you how to create, retrieve, and use short URLs.

Prerequisites

Before you begin, make sure you have completed the Installation Guide and both the backend and frontend are running.

Creating Your First Short URL

Using the Web Interface

  1. Open your browser to http://localhost:8000 

  2. Enter a long URL in the input field:

    https://www.example.com/very/long/url/path/to/content

  3. Click “Shorten URL”

  4. You’ll receive a short URL like:

    http://localhost:3001/r/AbC123

  5. Copy and test the short URL - it will redirect to your original URL!

Using the API (curl)

Create a short URL using curl:

curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://www.example.com/very/long/url"
  }'

Response:

{
  "shortCode": "AbC123",
  "longUrl": "https://www.example.com/very/long/url",
  "createdAt": "2024-01-01T12:00:00.000Z",
  "clicks": 0
}

Using the API (JavaScript)

const response = await fetch('http://localhost:3001/api/v1/urls', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    longUrl: 'https://www.example.com/very/long/url'
  })
});
 
const data = await response.json();
console.log('Short URL:', `http://localhost:3001/r/${data.shortCode}`);

Creating a Custom Short URL

Want a memorable short code? Use the customCode parameter:

Web Interface

  1. Click “Advanced Options” (if available)
  2. Enter your custom code (e.g., github)
  3. Click “Shorten URL”

API

curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://github.com/yourcompany",
    "customCode": "github"
  }'

Your URL will be available at: http://localhost:3001/r/github 

Custom Code Rules

  • Length: 4-20 characters
  • Characters: Alphanumeric only (a-z, A-Z, 0-9)
  • Uniqueness: Must not already exist

Setting an Expiration Date

Create temporary URLs that expire after a certain date:

curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://event.com/conference-2024",
    "expiresAt": "2024-12-31T23:59:59.000Z"
  }'

After the expiration date, accessing the short URL will return:

{
  "error": "Short URL has expired"
}

With HTTP status 410 Gone.

Retrieving URL Details

Get information about a short URL without redirecting:

curl http://localhost:3001/api/v1/urls/AbC123

Response:

{
  "shortCode": "AbC123",
  "longUrl": "https://www.example.com/very/long/url",
  "createdAt": "2024-01-01T12:00:00.000Z",
  "clicks": 5,
  "lastAccessedAt": "2024-01-01T13:30:00.000Z"
}

Viewing Analytics

Get Statistics for All URLs

curl http://localhost:3001/api/v1/stats

Response:

{
  "totalUrls": 150,
  "totalClicks": 1250,
  "activeUrls": 140,
  "expiredUrls": 10
}

Get Top URLs by Clicks

curl http://localhost:3001/api/v1/stats/top?limit=5

Response:

[
  {
    "shortCode": "popular",
    "longUrl": "https://example.com/trending",
    "clicks": 500,
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  {
    "shortCode": "AbC123",
    "longUrl": "https://example.com/article",
    "clicks": 250,
    "createdAt": "2024-01-01T06:00:00.000Z"
  }
]

Listing All URLs

Get a paginated list of all short URLs:

curl "http://localhost:3001/api/v1/urls?page=1&limit=10"

Response:

{
  "urls": [
    {
      "shortCode": "AbC123",
      "longUrl": "https://example.com/page1",
      "clicks": 10,
      "createdAt": "2024-01-01T12:00:00.000Z"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 10,
  "hasMore": true
}

Updating a URL

Change the destination of an existing short code:

curl -X PUT http://localhost:3001/api/v1/urls/AbC123 \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://example.com/new-destination"
  }'

The short code stays the same, but now redirects to the new URL.

Deleting a URL

Remove a short URL:

curl -X DELETE http://localhost:3001/api/v1/urls/AbC123

Returns HTTP status 204 No Content on success.

Testing the Redirect

Once you’ve created a short URL, test the redirect:

Browser

Simply visit the short URL in your browser:

http://localhost:3001/r/AbC123

curl (follow redirects)

curl -L http://localhost:3001/r/AbC123

The -L flag tells curl to follow the 302 redirect.

curl (see redirect headers)

curl -I http://localhost:3001/r/AbC123

Response:

HTTP/1.1 302 Found
Location: https://www.example.com/very/long/url

Common Use Cases

1. Marketing Campaign

curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://yoursite.com/summer-sale-2024",
    "customCode": "summer24",
    "expiresAt": "2024-09-01T00:00:00.000Z"
  }'

Share: http://localhost:3001/r/summer24 

curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://twitter.com/yourcompany/status/123456789",
    "customCode": "tweet123"
  }'
curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://jira.company.com/browse/PROJ-1234",
    "customCode": "jira1234"
  }'

Next Steps

Now that you’ve created your first short URLs:

Troubleshooting

”Short URL not found” Error

  • Verify the short code is correct
  • Check that the backend server is running
  • Ensure the URL hasn’t been deleted

”Custom code is already in use” Error

Choose a different custom code - each must be unique.

CORS Errors

Make sure both backend and frontend are running and the API URL is configured correctly in the frontend.

QuickstartIntroduction