SnapShot

Photo Management API Documentation

Overview

This is a RESTful photo management API that provides functionality for capturing, storing, listing, and deleting photos. The application also integrates with Immich (a self-hosted photo management service) for cloud backup and album organization.

Architecture

Configuration

The application requires the following environment variables:

Variable Description Required Example
IMMICH_BASE_URL Base URL of your Immich instance Yes https://photos.example.com/api
IMMICH_API_KEY API key for Immich authentication Yes your-immich-api-key
IMMICH_ALBUM_ID Target album ID in Immich for uploads Yes album-uuid-here

File Structure

/
├── photos/                 # Local photo storage directory
├── public/                 # Static web files
│   └── index.html         # Main web interface
├── index.js               # Main application file
└── .env                   # Environment configuration

API Endpoints

1. Web Interface

Endpoint: GET /

Description: Serves the main web interface for the photo management application.

Response: HTML page

Status Codes:


2. List Photos

Endpoint: GET /photos

Description: Retrieves a list of all stored photos in the local directory.

Request: No body required

Response:

[
  "photo-1640995200000.png",
  "photo-1640995260000.png",
  "photo-1640995320000.png"
]

Status Codes:


3. Access Photo Files

Endpoint: GET /photos/{filename}

Description: Serves individual photo files as static content.

Parameters:

Response: Binary image data

Status Codes:


4. Save Photo

Endpoint: POST /photos

Description: Saves a base64-encoded photo locally and uploads it to Immich cloud storage with album assignment.

Request Headers:

Content-Type: application/json

Request Body:

{
  "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA..."
}

Request Fields:

Response:

{
  "message": "Photo saved: photo-1640995200000.png",
  "path": "./photos/photo-1640995200000.png"
}

Workflow:

  1. Validates base64 photo data
  2. Generates timestamped filename
  3. Saves file to local photos/ directory
  4. Uploads to Immich cloud storage
  5. Adds photo to specified Immich album

Status Codes:


5. Delete Photo

Endpoint: DELETE /photos/{filename}

Description: Deletes a photo from local storage.

Parameters:

Response:

{
  "message": "Photo deleted"
}

Status Codes:

Note: This endpoint only deletes from local storage, not from Immich cloud storage.


6. Get Album URL

Endpoint: GET /album-url

Description: Retrieves the Immich album URL for QR code generation.

Request: No body required

Response:

{
  "album_url": "https://photos.example.com/albums/album-uuid-here"
}

Status Codes:

Note: The album URL is constructed from the IMMICH_BASE_URL and IMMICH_ALBUM_ID environment variables.


Data Formats

Photo Naming Convention

Photos are automatically named using the pattern: photo-{timestamp}.png

Base64 Image Format

Images should be provided as data URIs with the following format:

data:image/{type};base64,{base64-encoded-data}

Supported image types:

Immich Integration

The application automatically performs the following Immich operations when saving photos:

Asset Upload

Album Assignment

Error Handling

All endpoints return JSON error responses in the following format:

{
  "error": "Error description"
}

Common error scenarios:

Security Considerations

Dependencies

The application requires:

Usage Examples

Save a Photo (curl)

curl -X POST http://localhost:3000/photos \
  -H "Content-Type: application/json" \
  -d '{"photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."}'

List Photos (curl)

curl http://localhost:3000/photos

Delete Photo (curl)

curl -X DELETE http://localhost:3000/photos/photo-1640995200000.png

Access Photo (browser)

http://localhost:3000/photos/photo-1640995200000.png