Skip to main content

​
Overview

Secure Link API is a Java Spring Boot application that creates secure, expiring links with password protection and access limits. This quickstart will guide you through installation, creating your first link, and accessing statistics.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Java 21+ - Required for Spring Boot 4.0.2
  • Maven - For building and running the application
  • MySQL 8.4+ - For production/dev database
  • Git - For cloning the repository

​
Installation

1

Clone the repository

Clone the Secure Link API repository from GitHub:
git clone https://github.com/WalysonGomes/secure-link-api.git
cd secure-link-api/backend
2

Configure the database

Set up your MySQL database and configure the connection. Create a .env file or set environment variables:
export DB_HOST=localhost
export DB_PORT=3307
export DB_NAME=secure_link
export DB_USERNAME=your_user
export DB_PASSWORD=your_password
The application uses Flyway for database migrations, so tables will be created automatically on first run.
3

Start the server

Run the application using Maven with the dev profile:
SPRING_PROFILES_ACTIVE=dev mvn spring-boot:run
The API will start on http://localhost:8080
4

Verify installation

Check that the API is running by accessing the health endpoint:
curl http://localhost:8080/actuator/health

{
  "status": "UP",
  "components": {
    "db": { "status": "UP" },
    "diskSpace": { "status": "UP" },
    "ping": { "status": "UP" }
  }
}

​
URL Shortener

Create a secure link that redirects to an external URL: 
curl -X POST http://localhost:8080/api/links \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://example.com/document.pdf",
    "expiresAt": "2026-12-31T23:59:59Z",
    "maxViews": 10,
    "password": "secret123"
  }'
Response: 
{
  "shortCode": "K2x9pLmN",
  "accessUrl": "http://localhost:8080/l/K2x9pLmN",
  "expiresAt": "2026-12-31T23:59:59Z",
  "maxViews": 10
}

​
File Upload

Upload a file and generate a secure download link: 
curl -X POST http://localhost:8080/api/links/upload \
  -F "file=@/path/to/document.pdf" \
  -F "maxViews=5" \
  -F "password=secure_file"
Access a link without password protection: 
curl -i http://localhost:8080/l/K2x9pLmN
Response: HTTP 302 redirect to the target URL For links with password protection, provide the password in the X-Link-Password header: 
curl -i http://localhost:8080/l/K2x9pLmN \
  -H "X-Link-Password: secret123"

​
Response Codes

StatusResultDescription
302RedirectLink is valid, redirecting to target URL
200DownloadFile download initiated
401Password RequiredLink requires password authentication
404Not FoundLink does not exist
410GoneLink expired, revoked, or view limit reached

​
Viewing Statistics

​
Access Summary

Get overall access statistics with efficiency metrics: 
curl http://localhost:8080/api/stats/access/summary
Response: 
{
  "total": 1250,
  "success": 1050,
  "failed": 200,
  "expired": 45,
  "uniqueOrigins": 320,
  "accessEfficiencyRatio": 84.0,
  "expirationAttritionRate": 3.6
}
Check the status of all links in the system: 
curl http://localhost:8080/api/stats/links
Response: 
{
  "active": 42,
  "expired": 18,
  "revoked": 7
}
View the most frequently accessed links: 
curl http://localhost:8080/api/stats/links/top?limit=5

​
Hourly Access Distribution

Analyze access patterns by hour: 
curl http://localhost:8080/api/stats/access/hourly
Response: 
[
  { "hour": 14, "count": 150 },
  { "hour": 15, "count": 230 },
  { "hour": 16, "count": 180 }
]
Manually revoke a link to make it immediately inaccessible: 
curl -X DELETE http://localhost:8080/l/K2x9pLmN
Response: HTTP 204 No Content

​
Configuration Options

​
Environment Variables

VariableDescriptionDefault
DB_HOSTMySQL database hostlocalhost
DB_PORTMySQL database port3307
DB_NAMEDatabase namesecure_link
DB_USERNAMEDatabase usernameroot
DB_PASSWORDDatabase password-
SPRING_PROFILES_ACTIVEActive Spring profile (dev/prod/test)dev
SERVER_PORTHTTP server port8080

​
Application Properties

Key configuration options in application.properties: 
# Default TTL for links without expiration (24 hours)
app.link.default-ttl=PT24H

# Maximum file upload size
spring.servlet.multipart.max-file-size=50MB
spring.servlet.multipart.max-request-size=50MB

# File storage location
app.storage.path=/tmp/uploads/

# Base URL for generated links
app.base-url=http://localhost:8080

​
Next Steps

Core Concepts

Learn about link types, lifecycle, and validation

API Reference

Explore the complete API documentation

Authentication

Learn about API security and authentication

Monitoring

Set up Prometheus metrics and health checks

Deployment

Deploy to production environments

Access Control

Understand expiration, limits, and password protection

​
Troubleshooting

​
Database Connection Issues

If you encounter database connection errors:
  1. Verify MySQL is running: mysql -u root -p
  2. Check credentials in environment variables
  3. Ensure database exists: CREATE DATABASE secure_link;
  4. Verify MySQL version is 8.4+

​
File Upload Failures

If file uploads fail:
  1. Check file size is under 50MB
  2. Verify storage directory exists and is writable
  3. Check disk space: df -h

​
Authentication Errors

If password-protected links fail:
  1. Ensure password is sent in X-Link-Password header (not in body or query params)
  2. Verify password matches the one used during link creation
  3. Check for typos in the header name

​
Support

  • GitHub Repository: WalysonGomes/secure-link-api
  • Issues: Report bugs and feature requests on GitHub
  • Documentation: Full API reference and guides available in this documentation site

Build docs developers (and LLMs) love

Get started for freeTalk to us