API Overview¶

Swiftlink exposes a simple REST API for managing short links. The API is designed to be lightweight, fast, and easy to integrate with any programming language.

Architecture¶

The API is defined in the swiftlink-api crate, which serves as the single source of truth for: - Request and response types - Error handling - Client implementations (both async and blocking)

This ensures type safety and consistency between the server and client libraries.

Base URL¶

All API endpoints are relative to your Swiftlink server's base URL:

https://your-domain.com/api/

Authentication¶

Swiftlink uses a simple bearer token authentication system:

Public Endpoints¶

POST /api/create - Create short links
GET /api/info/{code} - Get link information
GET /{code} - Redirect to original URL

Protected Endpoints¶

DELETE /{code} - Delete short links (requires bearer token)

Bearer Token Usage¶

For protected endpoints, include the token in the Authorization header:

Authorization: Bearer your-secure-token-here

The bearer token is configured in the server's configuration file under base.bearer_token. If not set, the server generates one at startup and logs it.

Content Types¶

All API requests and responses use JSON format:

Content-Type: application/json

Error Handling¶

The API returns standard HTTP status codes:

200 OK - Request successful
302 Found - Redirect successful
400 Bad Request - Invalid request data
401 Unauthorized - Missing or invalid authentication
404 Not Found - Resource not found
500 Internal Server Error - Server error

Error responses include descriptive messages:

{
  "error": "Invalid URL format"
}

Rate Limiting¶

TODO

CORS¶

TODO

Endpoint Reference¶

For detailed endpoint documentation including request/response examples, see the Endpoints documentation.