Examples

This section provides practical usage examples for the Py URL Shortener API endpoints.

---

1. Shorten a URL

Request:

POST /api/v1/shorten
Content-Type: application/json

{
  "url": "https://www.youtube.com/watch?v=LYU-8IFcDPw",
  "expires_in": 60
}

Response:

{
  "short_url": "http://localhost/r/97ptsI",
  "code": "97ptsI",
  "created_at": "2025-10-22T15:54:30.650563",
  "expires_at": "2025-10-22T16:54:30.650610+00:00"
}

Explanation: This example shortens a YouTube link and sets it to expire in 60 minutes.

---

2. Redirect to Original URL

Request:

GET /r/97ptsI

Response: Redirects to the original URL: https://www.youtube.com/watch?v=LYU-8IFcDPw

Explanation: Every redirection logs a click event in the database, capturing IP, user-agent, referer, and timestamp.

---

3. Retrieve URL Statistics

Request:

GET /api/v1/stats/97ptsI

Response:

{
  "code": "97ptsI",
  "original_url": "https://www.youtube.com/watch?v=LYU-8IFcDPw",
  "created_at": "2025-10-22T15:54:30.650563",
  "expires_at": "2025-10-22T16:54:30.650610+00:00",
  "total_clicks": 3,
  "last_click_at": "2025-10-23T10:00:00.000000",
  "clicks": [
    {"click_id": 1, "time": "2025-10-22T10:00:00.000000"},
    {"click_id": 2, "time": "2025-10-22T11:00:00.000000"},
    {"click_id": 3, "time": "2025-10-23T10:00:00.000000"}
  ]
}

Explanation: Shows total clicks, last access, and individual click timestamps for analytics purposes.