This document provides a comprehensive specification of all REST API endpoints, authentication schemes, request/response structures, and behavior for the rust-base64-resolver-gen service.
The service supports separate API service tokens for LRU-cache operations and persistent storage operations.
- Cache Token (
cache_token): Required for in-memory LRU cache write operations (POST /api/cacheorPOST /imagewithtarget="cache"). - Storage Token (
storage_token): Required for persistent DB/cloud storage write operations (POST /api/storageorPOST /imagewithtarget="storage"ortarget="both").
Note: A valid
storage_tokenalso satisfies cache-level permissions because persistent storage is considered a higher privilege level. If a token is omitted or empty in configuration, authentication for that scope is open/unrestricted.
Clients can supply the token via any of the following methods:
- Standard Authorization Header:
Authorization: Bearer <your_token> - Dedicated Token Headers:
X-Cache-Token: <your_cache_token> X-Storage-Token: <your_storage_token> X-API-Token: <your_token> X-API-Key: <your_token>
- Query Parameter:
?token=<your_token>
| Method | Path | Auth Required | Purpose |
|---|---|---|---|
POST |
/api/cache |
cache_token |
Upload image directly into in-memory LRU cache |
POST |
/api/storage |
storage_token |
Upload image into persistent storage (semi-cached) |
POST |
/image |
cache_token / storage_token |
Unified upload with selectable target (cache, storage, both) |
POST |
/image/multipart |
cache_token / storage_token |
Multipart form upload with selectable target |
GET |
/image/{id} |
None (Public) | Retrieve image from LRU cache (falls back to storage if ID is a hash) |
GET |
/storage/{hash} |
None (Public) | Retrieve image by MD5 hash (semi-cached: RAM first, then storage) |
GET |
/md5/{hash} |
None (Public) | Alias for /storage/{hash} |
Stores an image exclusively in the fast in-memory LRU cache. It is assigned a unique UUID and also indexed by its content MD5 hash.
- URL:
/api/cache - Method:
POST - Headers:
Authorization: Bearer <cache_token>(orX-Cache-Token: <cache_token>)Content-Type: application/json(orapplication/x-www-form-urlencoded)
{
"base64": "<base64_encoded_image_data>",
"metaName": "temp_icon.png"
}base64(string, required): Raw base64 string or data URL (e.g.data:image/png;base64,...).metaName(string, optional): A descriptive label or filename.
{
"urlPath": "/image/6c7b3991-5369-42b7-8db1-9b7e71375ba3",
"id": "6c7b3991-5369-42b7-8db1-9b7e71375ba3",
"hash": "b10a8db164e0754105b7a99be72e3fe5",
"target": "cache",
"mimeType": "image/webp",
"originalSizeBytes": 348210,
"storedSizeBytes": 72410,
"savingsPercent": "79.2%",
"compressed": true,
"width": 800,
"height": 600
}400 Bad Request:{"error": "Invalid Base64 encoding: ..."}401 Unauthorized:{"error": "Unauthorized: Invalid or missing Cache API token"}
Stores an image into the configured persistent storage provider (PostgreSQL, MongoDB, S3, or Hetzner). The stored image is automatically warmed into the LRU memory cache so immediate reads are served directly from RAM.
- URL:
/api/storage - Method:
POST - Headers:
Authorization: Bearer <storage_token>(orX-Storage-Token: <storage_token>)Content-Type: application/json(orapplication/x-www-form-urlencoded)
{
"base64": "<base64_encoded_image_data>",
"metaName": "avatar.png"
}{
"urlPath": "/storage/b10a8db164e0754105b7a99be72e3fe5",
"dbUrlPath": "/md5/b10a8db164e0754105b7a99be72e3fe5",
"cacheUrlPath": "/image/e8f7a942-c112-4cba-a10f-627721865910",
"hash": "b10a8db164e0754105b7a99be72e3fe5",
"id": "e8f7a942-c112-4cba-a10f-627721865910",
"target": "storage",
"provider": "postgres",
"mimeType": "image/webp",
"originalSizeBytes": 348210,
"storedSizeBytes": 72410,
"savingsPercent": "79.2%",
"compressed": true,
"width": 800,
"height": 600,
"deduplicated": false
}deduplicated:trueif an identical image with this hash was already stored in the backend (content-addressable storage).
400 Bad Request:{"error": "Invalid Base64 encoding: ..."}401 Unauthorized:{"error": "Unauthorized: Invalid or missing Storage API token"}500 Internal Server Error:{"error": "Database storage failed: ..."}
A flexible endpoint that can route to LRU cache only, persistent storage only, or both.
- URL:
/image - Method:
POST - Headers:
Authorization: Bearer <token>Content-Type: application/jsonorapplication/x-www-form-urlencoded
{
"base64": "<base64_encoded_image_data>",
"target": "both",
"metaName": "profile.png"
}target(string, optional):"both"(default): Stores in persistent DB and LRU cache. Requiresstorage_token."storage": Stores in persistent DB and semi-caches. Requiresstorage_token."cache": Stores in LRU cache only. Requirescache_token.
{
"urlPath": "/image/e8f7a942-c112-4cba-a10f-627721865910",
"id": "e8f7a942-c112-4cba-a10f-627721865910",
"hash": "b10a8db164e0754105b7a99be72e3fe5",
"dbUrlPath": "/md5/b10a8db164e0754105b7a99be72e3fe5",
"storageUrlPath": "/storage/b10a8db164e0754105b7a99be72e3fe5",
"target": "both",
"provider": "mongodb",
"mimeType": "image/webp",
"originalSizeBytes": 348210,
"storedSizeBytes": 72410,
"savingsPercent": "79.2%",
"compressed": true,
"width": 800,
"height": 600,
"deduplicated": false
}Upload via multipart/form-data. Useful for direct HTML forms or tools posting binary or form fields.
- URL:
/image/multipart - Method:
POST - Form Fields:
base64(text): Base64-encoded image data.target(text, optional):"both","storage", or"cache".metaName(text, optional): Metadata name or filename.
Returns the same JSON response structure as POST /image.
Fetches an image by its UUID or hash.
- URL:
/image/{id} - Method:
GET - Resolution Order:
- Checks the in-memory LRU cache. If found, returns immediately.
- If missing from cache and
{id}is a 32-character hexadecimal MD5 hash, checks persistent storage. If found, caches in memory and returns. - Otherwise, returns
404 Not Found.
- Headers:
Content-Type: image/webp(orimage/png,image/jpeg,image/gif) - Body: Raw image binary bytes.
Fetches an image by its 32-character MD5 hash using the semi-cached retrieval pattern.
- URL:
/storage/{hash}or/md5/{hash} - Method:
GET - Resolution Order:
- RAM Check: Checks in-memory LRU cache. If present, returns immediately (sub-millisecond latency, 0 DB/S3 requests).
- Storage Lookup: Queries active storage backend (PostgreSQL, MongoDB, S3, Hetzner).
- Semi-Caching: Populates in-memory LRU cache with the retrieved payload.
- Returns the raw image binary bytes.
- Headers:
Content-Type: image/webp(orimage/png,image/jpeg) - Body: Raw image binary bytes.
Image not found
Whenever an image is posted to any endpoint, it passes through the built-in optimization engine:
- Auto Format Conversion: Non-WebP images are converted to WebP by default, achieving a 60–80% size reduction with perceptual near-lossless quality.
- EXIF / Metadata Stripping: Camera profiles, GPS tags, device metadata, and embedded thumbnails are stripped.
- Smart Downscaling: Images exceeding configured
max_widthormax_heightare proportionally resized using high-quality Lanczos3 filtering. - "Only If Smaller" Safety: If the compressed image happens to be larger than the original (e.g. tiny 16x16 pixel icons), the original bytes are kept.
- Deduplication: Content hashing guarantees identical images are stored only once.