API Design

Write Path — Creating a Short URL


Client → API Gateway → URL Write Service → KGS → PostgreSQL (primary) → Redis (warm)

Client sends POST /api/v1/urls with the long URL
API Gateway authenticates and rate-limits the request
Write Service calls KGS via gRPC to atomically acquire a unique short key
Write Service persists the mapping to PostgreSQL primary
Write Service warms Redis cache (async, best-effort)
Short URL is returned to the client

Endpoint:


POST /api/v1/urls
Headers: Authorization: Bearer <token>
         X-Idempotency-Key: <uuid>       # safe retries

Body:
{
  "long_url":     "https://example.com/some/very/long/path",
  "custom_alias": "my-key",              # optional
  "ttl_days":     30                     # optional, omit for permanent
}

201 Created:
{
  "short_url":   "https://short.ly/aB3dEfG",
  "short_key":   "aB3dEfG",
  "expires_at":  "2026-04-06T00:00:00Z"  # null if permanent
}

409 Conflict    → custom alias already taken
422 Unprocessable → long_url is malformed or blocklisted
429 Too Many Requests → rate limit exceeded

Other write endpoints:


DELETE /api/v1/urls/{short_key}          # soft-delete, owner-only → 204

Read Path — Redirecting a Short URL


Client → CDN (cache hit → 302) → API Gateway → Redirect Service → Redis → PostgreSQL (replica)

Client hits GET /{short_key} (e.g., clicking a link)
CDN checks edge cache — if hit, returns 302 immediately (< 5ms, no backend hit)
On cache miss, request reaches Redirect Service
Redirect Service checks Redis — hit returns 302 in < 2ms
On Redis miss, falls back to PostgreSQL read replica, then populates Redis
url.clicked event is published to Kafka asynchronously (non-blocking)

Endpoint:


GET /{short_key}

302 Found
  Location: https://original-long-url.com/...

404 Not Found   → key does not exist or has expired
410 Gone        → key was explicitly deleted

301 vs 302 decision: | | 301 Permanent | 302 Temporary | |-|--------------|---------------| | Browser caches redirect | Yes — no future server hit | No — every click hits server | | Click analytics possible | No | Yes | | CDN cache TTL | Long (days) | Short (minutes) | | Use when | No analytics needed, max caching | Analytics required (chosen) |

Internal API — Key Generation Service (gRPC)


service KeyGenerationService {
  rpc AcquireKey(AcquireKeyRequest) returns (AcquireKeyResponse);
}

message AcquireKeyRequest {}

message AcquireKeyResponse {
  string key = 1;  // 7-char Base62, guaranteed unique
}

Called only by URL Write Service. Not exposed externally.

Submissions

Displaying Solutions with Scores Ranging from 1 to 10