Skip to content

Latest commit

 

History

History
122 lines (99 loc) · 2.27 KB

API.md

File metadata and controls

122 lines (99 loc) · 2.27 KB

API Reference

Base URL

http://localhost:8080

Endpoints

Create Short URL

POST /urls
Content-Type: application/json

{
  "long_url": "https://www.example.com",
  "expiration_date": "2025-12-31T23:59:59Z"  // optional
}

Response (200)

{
  "short_url": "http://localhost:8080/1"
}

Redirect to Long URL

GET /{shortCode}

Returns 302 Found redirect to the original URL.

Get URL Statistics

GET /urls/{shortCode}/stats

Response (200)

{
  "short_code": "1",
  "long_url": "https://www.example.com",
  "created_at": "2025-07-19T17:30:00Z",
  "expiration_date": "2025-12-31T23:59:59Z",
  "id": 1
}

Health Check

GET /health

Response (200)

{
  "status": "healthy",
  "stats": {
    "total_urls": 1,
    "current_counter": 1,
    "storage_type": "redis"
  }
}

Examples

cURL

# Create short URL
curl -X POST http://localhost:8080/urls \
  -H "Content-Type: application/json" \
  -d '{"long_url": "https://www.github.com"}'

# Access short URL
curl -L http://localhost:8080/1

# Get statistics
curl http://localhost:8080/urls/1/stats

# Health check
curl http://localhost:8080/health

JavaScript

// Create short URL
const response = await fetch('http://localhost:8080/urls', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ long_url: 'https://www.github.com' })
});

const data = await response.json();
console.log(data.short_url); // http://localhost:8080/1

Error Responses

400 Bad Request - Invalid URL format or JSON
404 Not Found - Short code doesn't exist
429 Too Many Requests - Rate limit exceeded (20 req/min per IP)
500 Internal Server Error - Storage error

Rate Limiting

The API implements per-IP rate limiting:

  • Limit: 20 requests per minute per IP address
  • Algorithm: Token bucket with automatic refill
  • Headers: Returns X-RateLimit-* headers in responses
  • Response: 429 status with retry-after information when exceeded

Notes

  • URLs must start with http:// or https://
  • Short codes use Base62 encoding (0-9A-Za-z)
  • Expired URLs return 404 when accessed
  • CORS enabled for browser requests
  • Rate limiting applies to all endpoints per IP address