Skip to content

Latest commit

 

History

History
252 lines (199 loc) · 8.71 KB

API_DOCS.md

File metadata and controls

252 lines (199 loc) · 8.71 KB

API Documentation (API_DOCS.md)

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.


1. Authentication

The service supports separate API service tokens for LRU-cache operations and persistent storage operations.

Configured Tokens

  • Cache Token (cache_token): Required for in-memory LRU cache write operations (POST /api/cache or POST /image with target="cache").
  • Storage Token (storage_token): Required for persistent DB/cloud storage write operations (POST /api/storage or POST /image with target="storage" or target="both").

Note: A valid storage_token also 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.

How to Supply Tokens

Clients can supply the token via any of the following methods:

  1. Standard Authorization Header:
    Authorization: Bearer <your_token>
  2. 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>
  3. Query Parameter:
    ?token=<your_token>

2. Endpoints Overview

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}

3. Detailed Endpoint Specifications

3.1. Post to LRU Cache

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> (or X-Cache-Token: <cache_token>)
    • Content-Type: application/json (or application/x-www-form-urlencoded)

Request Body

{
  "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.

Response: 200 OK

{
  "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
}

Error Responses

  • 400 Bad Request: {"error": "Invalid Base64 encoding: ..."}
  • 401 Unauthorized: {"error": "Unauthorized: Invalid or missing Cache API token"}

3.2. Post to Persistent Storage (Semi-Cached)

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> (or X-Storage-Token: <storage_token>)
    • Content-Type: application/json (or application/x-www-form-urlencoded)

Request Body

{
  "base64": "<base64_encoded_image_data>",
  "metaName": "avatar.png"
}

Response: 200 OK

{
  "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: true if an identical image with this hash was already stored in the backend (content-addressable storage).

Error Responses

  • 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: ..."}

3.3. Unified Upload (/image)

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/json or application/x-www-form-urlencoded

Request Body

{
  "base64": "<base64_encoded_image_data>",
  "target": "both",
  "metaName": "profile.png"
}
  • target (string, optional):
    • "both" (default): Stores in persistent DB and LRU cache. Requires storage_token.
    • "storage": Stores in persistent DB and semi-caches. Requires storage_token.
    • "cache": Stores in LRU cache only. Requires cache_token.

Response: 200 OK

{
  "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
}

3.4. Multipart Upload (/image/multipart)

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.


3.5. Retrieve Image by Cache ID (/image/{id})

Fetches an image by its UUID or hash.

  • URL: /image/{id}
  • Method: GET
  • Resolution Order:
    1. Checks the in-memory LRU cache. If found, returns immediately.
    2. If missing from cache and {id} is a 32-character hexadecimal MD5 hash, checks persistent storage. If found, caches in memory and returns.
    3. Otherwise, returns 404 Not Found.

Response: 200 OK

  • Headers: Content-Type: image/webp (or image/png, image/jpeg, image/gif)
  • Body: Raw image binary bytes.

3.6. Retrieve Image by Persistent Storage Hash (/storage/{hash} or /md5/{hash})

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:
    1. RAM Check: Checks in-memory LRU cache. If present, returns immediately (sub-millisecond latency, 0 DB/S3 requests).
    2. Storage Lookup: Queries active storage backend (PostgreSQL, MongoDB, S3, Hetzner).
    3. Semi-Caching: Populates in-memory LRU cache with the retrieved payload.
    4. Returns the raw image binary bytes.

Response: 200 OK

  • Headers: Content-Type: image/webp (or image/png, image/jpeg)
  • Body: Raw image binary bytes.

Response: 404 Not Found

  • Image not found

4. Image Optimization & Compression

Whenever an image is posted to any endpoint, it passes through the built-in optimization engine:

  1. Auto Format Conversion: Non-WebP images are converted to WebP by default, achieving a 60–80% size reduction with perceptual near-lossless quality.
  2. EXIF / Metadata Stripping: Camera profiles, GPS tags, device metadata, and embedded thumbnails are stripped.
  3. Smart Downscaling: Images exceeding configured max_width or max_height are proportionally resized using high-quality Lanczos3 filtering.
  4. "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.
  5. Deduplication: Content hashing guarantees identical images are stored only once.