LinkGuard API Documentation

API references for the LinkGuard backend service. Includes authentication, profile management, URL expansion, and trending analytics.

Base URL: http://localhost:8080

Endpoints Quick Index

POST /api/auth/register

Register a new user

Creates a new user account. Returns the created user's details.

Request Body

Field Type Required Description
username string Yes * Username for the account (3-20 characters). Example: "modhtom"
mail string Yes * User's email address. Example: "modhtom@example.com"
password_unHashed string Yes * User's password (min 6 characters). Example: "password123"
JSON Payload Schema
{
  "username": "modhtom",
  "mail": "modhtom@example.com",
  "password_unHashed": "password123"
}

Responses

User successfully created.

Response Body (UserRespondDTO)
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "username": "modhtom",
  "mail": "modhtom@example.com",
  "enabled": true,
  "created_at": "2026-07-20T21:20:46Z",
  "updated_at": "2026-07-20T21:20:46Z"
}

Invalid user data provided or username is already taken.

Response Body
{
  "id": null,
  "username": null,
  "mail": null,
  "enabled": false,
  "created_at": null,
  "updated_at": null
}
POST /api/auth/login

Authenticate a user

Verifies a user's credentials and returns a JWT (JSON Web Token) upon success.

Request Body

Field Type Required Description
username string Yes * Username for the account. Example: "modhtom"
mail string Yes * User's email address. Example: "modhtom@example.com"
password_unHashed string Yes * User's password. Example: "password123"
JSON Payload Schema
{
  "username": "modhtom",
  "mail": "modhtom@example.com",
  "password_unHashed": "password123"
}

Responses

Authentication successful. Returns JWT string.

Response Body (string)
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Invalid credentials provided.

Response Body
"Invalid username or password"
GET /api/users/me Bearer Authentication

Get current user's details

Fetches the profile information for the currently authenticated user based on their JWT.

Responses

User details retrieved successfully.

Response Body (UserRespondDTO)
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "username": "modhtom",
  "mail": "modhtom@example.com",
  "enabled": true,
  "created_at": "2026-07-20T21:20:46Z",
  "updated_at": "2026-07-20T21:20:46Z"
}

User is not authenticated.

PUT /api/users/edit Bearer Authentication

Update a user's profile

Allows an authenticated user to update their own profile information (e.g., email, password).

Request Body

Field Type Required Description
username string Yes * New username. Example: "modhtom"
mail string Yes * New email address. Example: "modhtom@example.com"
password_unHashed string Yes * New plain text password. Example: "password123"
JSON Payload Schema
{
  "username": "newUsername",
  "mail": "newmail@example.com",
  "password_unHashed": "newsecurepwd123"
}

Responses

Profile updated successfully.

Response Body (UserRespondDTO)
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "username": "newUsername",
  "mail": "newmail@example.com",
  "enabled": true,
  "created_at": "2026-07-20T21:20:46Z",
  "updated_at": "2026-07-20T21:25:34Z"
}

Invalid data provided.

User is not authenticated.

POST /api/urls/v1/expand Bearer Authentication

Expand short URL

Submit a short URL and receive expanded details. Results are automatically cached in Redis.

Request Body

Field Type Required Description
url string Yes * The short URL to expand. Example: "https://tinyurl.com/34775fb4"
JSON Payload Schema
{
  "url": "https://tinyurl.com/34775fb4"
}

Responses

Receive expanded details successfully.

Response Body (UrlRespondDTO)
{
  "id": "e9b213d4-f6e5-4890-2341-a67890abcdef",
  "shortUrl": "https://tinyurl.com/34775fb4",
  "finalUrl": "https://example.com/target-page",
  "domain": "example.com",
  "title": "Example Domain Target",
  "description": "This is the target web page that the short link redirects to."
}

Invalid URL or data provided.

User is not authenticated.