Tiny-Urls: Efficient Short Link Generation API

Tiny-Urls offers a powerful API for creating and managing short links through the /api/share endpoint. This endpoint is designed to generate or reuse short URLs that redirect to external sites, enhancing link sharing and accessibility in digital applications.

API Endpoint

• URL: POST /api/share
• Purpose: Generate a short link that simplifies the sharing of long URLs.
• Content Type: application/json

Request Body Structure

To utilize the Tiny-Urls API, send a JSON payload containing:

{
  "url": "https://example.com/article",
  "expiration": "7d"
}

• url (string, required): The complete destination URL. Only http and https are allowed.
• expiration (string, optional): Defines the duration the short link remains active. Valid options include:
  • 12h (12 hours)
  • 7d (7 days, default)
  • 180d (180 days, maximum)
• expiresAt (number, optional): A Unix timestamp specifying when the link should expire, overriding the expiration period.

Response Codes

On a successful request, the API returns:

• Status 201: If a new short link is created.
• Status 200: If an existing, non-expired link for the input URL is reused.

The response will take the form:

{
  "success": true,
  "shortPath": "abcd",
  "shortUrl": "https://short.example.com/abcd",
  "originalUrl": "https://example.com/article",
  "isExisting": false,
  "expiresAt": 1726000000000
}

• shortPath (string): The generated 4-character slug for the shortened URL.
• shortUrl (string): The full short URL provided in the response.
• originalUrl (string): The original URL sent in the request.
• isExisting (boolean): Indicates whether an existing link was reused.
• expiresAt (number|null): Timestamp for link expiration; null for legacy links without an expiry.

Error Handling

In case of issues, the API will return relevant error messages based on the problem encountered:

• 400: If the request has an invalid payload.
• 403: If the request origin is not allowed by CORS policy.
• 500: For internal errors during short path generation.

Errors are structured as:

{ "error": "message" }

Example Usage with Curl

To create a short link, use the following Curl command:

curl -X POST https://short.example.com/api/share \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","expiration":"180d"}'

Or, specify an expiration directly:

curl -X POST https://short.example.com/api/share \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","expiresAt":1726000000000}'

CORS Configuration

The API maintains a security layer by serving responses only to pre-approved origins:

Set these variables with appropriate commands in your deployment dashboard or through wrangler secret put.

Additional Notes

• The system automatically purges expired links and caches current ones using Cloudflare KV for optimized lookup speeds.
• Consider implementing rate limiting and authentication as needed for additional security.