Link Shortener API Documentation#

Base URL#

http://localhost:8080

Endpoints#

Health Check#

Check if the service and database are running.

GET /health

Example:

curl http://localhost:8080/health

Response (200 OK):

"Healthy"

Response (503 Service Unavailable):

"Database unavailable"

Create Short URL#

Create a new shortened URL with optional custom code.

POST /api/shorten

Request Body:

{
  "url": string,           // Required: The URL to shorten
  "custom_code": string,   // Optional: Custom short code
  "source": string        // Optional: Source of the request
}

Examples:

1. Create with auto-generated code:

curl -X POST http://localhost:8080/api/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "source": "curl-test"
  }'

Response (201 Created):

{
  "id": 1,
  "original_url": "https://example.com",
  "short_code": "Xa7Bc9",
  "created_at": "2024-03-01T12:34:56Z",
  "clicks": 0
}

2. Create with custom code:

curl -X POST http://localhost:8080/api/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "custom_code": "example",
    "source": "curl-test"
  }'

Response (201 Created):

{
  "id": 2,
  "original_url": "https://example.com",
  "short_code": "example",
  "created_at": "2024-03-01T12:34:56Z",
  "clicks": 0
}

Error Responses:

Invalid URL (400 Bad Request):

{
  "error": "URL must start with http:// or https://"
}

Custom code taken (400 Bad Request):

{
  "error": "Custom code already taken"
}

Invalid custom code (400 Bad Request):

{
  "error": "Custom code must be 1-32 characters long and contain only letters, numbers, underscores, and hyphens"
}

Get All Links#

Retrieve all shortened URLs.

GET /api/links

Example:

curl http://localhost:8080/api/links

Response (200 OK):

[
  {
    "id": 1,
    "original_url": "https://example.com",
    "short_code": "Xa7Bc9",
    "created_at": "2024-03-01T12:34:56Z",
    "clicks": 5
  },
  {
    "id": 2,
    "original_url": "https://example.org",
    "short_code": "example",
    "created_at": "2024-03-01T12:35:00Z",
    "clicks": 3
  }
]

Redirect to Original URL#

Use the shortened URL to redirect to the original URL.

GET /{short_code}

Example:

curl -i http://localhost:8080/example

Response (307 Temporary Redirect):

HTTP/1.1 307 Temporary Redirect
Location: https://example.com

Error Response (404 Not Found):

{
  "error": "Not found"
}

Custom Code Rules#

1. Length: 1-32 characters
2. Allowed characters: letters, numbers, underscores, and hyphens
3. Case-sensitive
4. Cannot use reserved words: ["api", "health", "admin", "static", "assets"]

Rate Limiting#

Currently, no rate limiting is implemented.

Notes#

1. All timestamps are in UTC
2. Click counts are incremented on successful redirects
3. Source tracking is optional but recommended for analytics
4. Custom codes are case-sensitive
5. URLs must include protocol (http:// or https://)

Error Codes#

• 200: Success
• 201: Created
• 307: Temporary Redirect
• 400: Bad Request (invalid input)
• 404: Not Found
• 503: Service Unavailable

Database Schema#

CREATE TABLE links (
    id SERIAL PRIMARY KEY,
    original_url TEXT NOT NULL,
    short_code VARCHAR(8) NOT NULL UNIQUE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    clicks BIGINT NOT NULL DEFAULT 0
);

CREATE TABLE clicks (
    id SERIAL PRIMARY KEY,
    link_id INTEGER REFERENCES links(id),
    source TEXT,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);