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

API Endpoints

Complete reference for all REST API endpoints provided by the URL Shortener service.

Base URL


http://localhost:3001/api/v1

For production, replace with your domain.

Authentication

Currently, the API does not require authentication. All endpoints are publicly accessible.

Note: For production deployments, consider adding authentication for management endpoints (create, update, delete).

URL Management

Create Short URL

Create a new shortened URL with an automatically generated or custom short code.

Endpoint: POST /api/v1/urls

Request Body:

Field	Type	Required	Description
`longUrl`	string	Yes	The URL to shorten (must be valid URL with protocol)
`customCode`	string	No	Custom short code (4-20 alphanumeric characters)
`expiresAt`	string	No	Expiration datetime in ISO 8601 format

Example Request:


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

Success Response (201 Created):


{
  "shortCode": "example",
  "longUrl": "https://www.example.com/very/long/url",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "clicks": 0
}

Error Responses:

400 Bad Request - Invalid input:


{
  "errors": [
    {
      "path": ["longUrl"],
      "message": "Must be a valid URL"
    }
  ]
}

400 Bad Request - Custom code in use:


{
  "error": "Custom code is already in use"
}

Code Reference: backend/src/routes.ts:42

Get URL Details

Retrieve information about a shortened URL by its short code.

Endpoint: GET /api/v1/urls/:shortCode

Path Parameters:

Parameter	Type	Description
`shortCode`	string	The short code identifier

Example Request:


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

Success Response (200 OK):


{
  "shortCode": "example",
  "longUrl": "https://www.example.com/very/long/url",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "clicks": 42,
  "lastAccessedAt": "2024-01-15T14:20:00.000Z"
}

Error Response:

404 Not Found:


{
  "error": "Short URL not found"
}

Code Reference: backend/src/routes.ts:101

List All URLs

Get a paginated list of all shortened URLs in the system.

Endpoint: GET /api/v1/urls

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`limit`	integer	10	Items per page (max 100)

Example Request:


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

Success Response (200 OK):


{
  "urls": [
    {
      "shortCode": "example",
      "longUrl": "https://www.example.com/page1",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clicks": 42
    },
    {
      "shortCode": "AbC123",
      "longUrl": "https://www.example.com/page2",
      "createdAt": "2024-01-15T11:00:00.000Z",
      "clicks": 15
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "hasMore": true
}

Code Reference: backend/src/routes.ts:132

Update URL

Update the destination (long URL) for an existing short code.

Endpoint: PUT /api/v1/urls/:shortCode

Path Parameters:

Parameter	Type	Description
`shortCode`	string	The short code to update

Request Body:

Field	Type	Required	Description
`longUrl`	string	Yes	New destination URL

Example Request:


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

Success Response (200 OK):


{
  "shortCode": "example",
  "longUrl": "https://www.example.com/new-destination",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "clicks": 42,
  "lastAccessedAt": "2024-01-15T14:20:00.000Z"
}

Error Responses:

404 Not Found:


{
  "error": "Short URL not found"
}

400 Bad Request:


{
  "errors": [
    {
      "path": ["longUrl"],
      "message": "Must be a valid URL"
    }
  ]
}

Code Reference: backend/src/routes.ts:183

Delete URL

Permanently remove a shortened URL from the system.

Endpoint: DELETE /api/v1/urls/:shortCode

Path Parameters:

Parameter	Type	Description
`shortCode`	string	The short code to delete

Example Request:


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

Success Response (204 No Content):

No response body.

Error Response:

404 Not Found:


{
  "error": "Short URL not found"
}

Code Reference: backend/src/routes.ts:225

Redirect

Redirect to Long URL

Redirect the user to the original long URL. This increments the click counter.

Endpoint: GET /r/:shortCode

Note: This endpoint is at the root level, not under /api/v1.

Path Parameters:

Parameter	Type	Description
`shortCode`	string	The short code to redirect

Example Request:


# Follow redirect
curl -L http://localhost:3001/r/example
 
# See redirect without following
curl -I http://localhost:3001/r/example

Success Response (302 Found):


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

Error Responses:

404 Not Found:


{
  "error": "Short URL not found"
}

410 Gone (expired):


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

Side Effects:

Increments the clicks counter
Updates lastAccessedAt timestamp

Code Reference: backend/src/index.ts:32

Statistics

Get Global Statistics

Retrieve aggregate statistics for the entire service.

Endpoint: GET /api/v1/stats

Example Request:


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

Success Response (200 OK):


{
  "totalUrls": 1523,
  "totalClicks": 45829,
  "activeUrls": 1489,
  "expiredUrls": 34
}

Fields:

Field	Type	Description
`totalUrls`	integer	Total number of URLs in the system
`totalClicks`	integer	Sum of all clicks across all URLs
`activeUrls`	integer	Number of non-expired URLs
`expiredUrls`	integer	Number of expired URLs

Code Reference: backend/src/routes.ts:283

Get Top URLs by Clicks

Retrieve the most popular URLs sorted by click count.

Endpoint: GET /api/v1/stats/top

Query Parameters:

Parameter	Type	Default	Description
`limit`	integer	10	Number of results to return (max 50)

Example Request:


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

Success Response (200 OK):


[
  {
    "shortCode": "popular",
    "longUrl": "https://example.com/trending-article",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "clicks": 500,
    "lastAccessedAt": "2024-01-15T14:30:00.000Z"
  },
  {
    "shortCode": "viral",
    "longUrl": "https://example.com/viral-video",
    "createdAt": "2024-01-02T00:00:00.000Z",
    "clicks": 350,
    "lastAccessedAt": "2024-01-15T13:45:00.000Z"
  }
]

Note: Only includes non-expired URLs.

Code Reference: backend/src/routes.ts:312

Utility Endpoints

Health Check

Check if the service is running and healthy.

Endpoint: GET /health

Example Request:


curl http://localhost:3001/health

Success Response (200 OK):


{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Use Cases:

Load balancer health checks
Monitoring systems
Deployment verification

Code Reference: backend/src/index.ts:74

API Information

Get general information about the API, including available endpoints.

Endpoint: GET /

Example Request:


curl http://localhost:3001/

Success Response (200 OK):


{
  "message": "URL Shortener API",
  "version": "1.0.0",
  "documentation": "/api-docs",
  "endpoints": {
    "create": "POST /api/v1/urls",
    "get": "GET /api/v1/urls/:shortCode",
    "list": "GET /api/v1/urls",
    "update": "PUT /api/v1/urls/:shortCode",
    "delete": "DELETE /api/v1/urls/:shortCode",
    "redirect": "GET /r/:shortCode",
    "stats": "GET /api/v1/stats",
    "top": "GET /api/v1/stats/top"
  },
  "baseUrl": "http://localhost:3001"
}

Code Reference: backend/src/index.ts:54

HTTP Status Codes

The API uses standard HTTP status codes:

Code	Meaning	Usage
200	OK	Successful GET, PUT requests
201	Created	Successful POST (create)
204	No Content	Successful DELETE
302	Found	Redirect to long URL
400	Bad Request	Validation error, invalid input
404	Not Found	Resource doesn’t exist
410	Gone	URL has expired
500	Internal Server Error	Unexpected server error

Rate Limiting

Note: Rate limiting is not currently implemented but recommended for production.

Recommended Implementation:


import rateLimit from 'express-rate-limit';
 
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // 100 requests per window
  message: { error: 'Too many requests, please try again later' }
});
 
app.use('/api/', limiter);

CORS

Cross-Origin Resource Sharing (CORS) is enabled for all origins in development.

Current Configuration:


app.use(cors()); // Allow all origins

Production Configuration:


app.use(cors({
  origin: ['https://yourfrontend.com'],
  credentials: true
}));

Interactive Documentation

The API includes interactive Swagger/OpenAPI documentation.

Access: http://localhost:3001/api-docs

Features:

Try out endpoints directly in the browser
See request/response schemas
Download OpenAPI specification
Generate client SDKs

Error Handling

All error responses follow a consistent format:

Single Error:


{
  "error": "Error message here"
}

Validation Errors (Multiple):


{
  "errors": [
    {
      "path": ["fieldName"],
      "message": "Error message here"
    }
  ]
}

Examples

Complete URL Lifecycle


# 1. Create a short URL
curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com/article"}'
# Response: {"shortCode": "AbC123", ...}
 
# 2. Get URL details
curl http://localhost:3001/api/v1/urls/AbC123
# Response: {"shortCode": "AbC123", "clicks": 0, ...}
 
# 3. Use the short URL (redirect)
curl -L http://localhost:3001/r/AbC123
# Redirects to https://example.com/article
 
# 4. Check updated stats
curl http://localhost:3001/api/v1/urls/AbC123
# Response: {"shortCode": "AbC123", "clicks": 1, ...}
 
# 5. Update destination
curl -X PUT http://localhost:3001/api/v1/urls/AbC123 \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com/new-article"}'
 
# 6. Delete URL
curl -X DELETE http://localhost:3001/api/v1/urls/AbC123
# Response: 204 No Content

Creating URLs with Different Options


# Auto-generated code
curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com"}'
 
# Custom code
curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com", "customCode": "mylink"}'
 
# With expiration
curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://example.com",
    "expiresAt": "2024-12-31T23:59:59.000Z"
  }'
 
# All options combined
curl -X POST http://localhost:3001/api/v1/urls \
  -H "Content-Type: application/json" \
  -d '{
    "longUrl": "https://example.com",
    "customCode": "promo",
    "expiresAt": "2024-12-31T23:59:59.000Z"
  }'

Next Steps

Quick Start Guide - Try the API
Data Models - Understand data structures
Development Setup - Build and extend the API