FOUNDATION

Introduction

The Aesthetics API exposes a normalized collection of aesthetic names, slugs, source links, image filenames, and resolved image URLs through a compact read-only HTTP interface.

✦

Design goal

Keep the dataset portable and the API predictable. Records remain image-host agnostic while the server resolves the final image URL at response time.

01

Read only

No mutation endpoints, account state, sessions, or authorization flow.

02

Flat records

Small JSON objects that map directly into UI, scripts, and data pipelines.

03

Portable media

Switch between local files, a custom CDN, or source-hosted images without rewriting records.

02

SYSTEM MODEL

Architecture

CLIENTHTTP REQUESTGET /aesthetics/{slug}

→

FASTAPIROUTE LAYERvalidation + lookup

→

DATAAESTHETICS.JSONnormalized records

→

OUTPUTJSON RESPONSEresolved image_url

Data loading

The application loads the JSON dataset at startup and constructs a slug-addressable in-memory collection. This makes list, direct lookup, search, and random selection inexpensive at runtime.

Image resolution

The stored image value remains a filename. The response layer generates image_url from the active image delivery mode and base configuration.

03

LOCAL RUNTIME

Quickstart

01

Create an isolated Python environment

python3 -m venv .venv
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

02

Install the server and scraper dependencies

python -m pip install --upgrade pip
pip install "fastapi[standard]" uvicorn requests beautifulsoup4

03

Verify the expected project files

project/
├── api.py
├── aesthetics.json
└── images/
    ├── acid-design.png
    └── ...

04

Start the development server

uvicorn api:app --reload --host 127.0.0.1 --port 8000

◎

Health verification

Open http://127.0.0.1:8000/healthz. A healthy process returns status, record count, and active image mode.

04

RUNTIME CONTROL

Configuration

Keep deployment-specific values outside the dataset. The following table defines the configuration surface expected by this documentation baseline.

Variable	Purpose	Example	Required
`AESTHETICS_DATA`	Path to the JSON dataset.	`./aesthetics.json`	No
`IMAGE_MODE`	Image delivery strategy.	`local`, `cdn`, `source`	No
`IMAGE_DIR`	Filesystem directory used by local image mode.	`./images`	Local mode
`IMAGE_BASE_URL`	Public base URL used by custom CDN mode.	`https://cdn.example.com/aesthetics`	CDN mode
`PUBLIC_API_BASE`	Optional public base used when constructing absolute local URLs.	`https://api.example.com`	No

# Example local configuration
export AESTHETICS_DATA="./aesthetics.json"
export IMAGE_MODE="local"
export IMAGE_DIR="./images"

uvicorn api:app --host 0.0.0.0 --port 8000

05

HTTP CONTRACT

Endpoint reference

GET/aesthetics200 JSON

Returns the complete collection. Optional pagination parameters can be applied by clients that do not want the entire payload.

Query parameters

limit: Optional integer cap.
offset: Optional zero-based starting position.

Response shape

Array of Aesthetic objects.

curl -s "http://127.0.0.1:8000/aesthetics?limit=20&offset=0"

const response = await fetch(
  "http://127.0.0.1:8000/aesthetics?limit=20&offset=0"
);
const aesthetics = await response.json();

import requests

aesthetics = requests.get(
    "http://127.0.0.1:8000/aesthetics",
    params={"limit": 20, "offset": 0},
    timeout=10,
).json()

GET/aesthetics/{slug}200 / 404

Returns one exact record selected by canonical slug.

Path parameter

slug: Required lowercase URL-safe record identifier.

Failure behavior

An unknown slug returns 404 with a JSON error body.

curl -s http://127.0.0.1:8000/aesthetics/acid-design

GET/aesthetics/{slug}/imageIMAGE / REDIRECT

Resolves the primary moodboard media for a record. The exact transport behavior depends on the configured image mode.

Local mode

Returns the file response from the configured image directory.

Remote modes

Redirects to the generated CDN URL or the record's source image URL.

GET/random200 JSON

Returns one randomly selected aesthetic record.

curl -s http://127.0.0.1:8000/random

GET/search?q={query}200 / 422

Performs a case-insensitive substring search against aesthetic names.

Query parameter

q: Required search string.

Response shape

Array of matching Aesthetic objects. No match returns an empty array.

curl -s "http://127.0.0.1:8000/search?q=core"

GET/healthz200 JSON

Provides a lightweight liveness response and confirms that the dataset was loaded.

{
  "status": "ok",
  "count": 219,
  "image_mode": "local"
}

06

DATA CONTRACT

Data schemas

Aesthetic

OBJECT

Field	Type	Nullable	Description
`slug`	string	No	Canonical URL-safe identifier.
`name`	string	No	Human-readable aesthetic name.
`aesthetic_url`	URL string	No	Source article on the Aesthetics Wiki.
`image`	string	No	Portable image filename stored in the dataset.
`source_image_url`	URL string	Possible	Original source-hosted media URL.
`image_url`	URL string	No	Resolved public image location for the active server mode.

{
  "slug": "acid-design",
  "name": "Acid Design",
  "aesthetic_url": "https://aesthetics.fandom.com/wiki/Acid_Design",
  "image": "acid-design.png",
  "source_image_url": "https://static.wikia.nocookie.net/.../revision/latest",
  "image_url": "http://127.0.0.1:8000/images/acid-design.png"
}

07

FAILURE CONTRACT

Errors

404

Unknown record

The requested slug is not present in the loaded dataset.

404

Missing local image

The record exists, but the configured local image file cannot be read.

422

Invalid request

A required path or query value failed request validation.

500

Server failure

The process could not load or serialize required application data.

{
  "detail": "Aesthetic not found"
}

08

MEDIA ROUTING

Image delivery

01

Local filesystem

The API mounts or streams files from IMAGE_DIR. JSON responses resolve to the API's own image route or static mount.

http://127.0.0.1:8000/images/acid-design.png

02

Custom CDN

The server joins IMAGE_BASE_URL with each record's portable filename.

https://cdn.example.com/aesthetics/acid-design.png

03

Source host

The server exposes or redirects to source_image_url, avoiding local image storage.

https://static.wikia.nocookie.net/...

09

BROWSER ACCESS

CORS & clients

The landing-page explorer calls the API directly from the browser. Development deployments therefore need an origin policy that allows the page's host and HTTP method.

!

Production policy

Use explicit allowed origins for a public deployment rather than unrestricted wildcard configuration when credentials or private endpoints are ever introduced.

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://docs.example.com"],
    allow_methods=["GET"],
    allow_headers=["Accept", "Content-Type"],
)

10

MACHINE DESCRIPTION

OpenAPI

SWAGGER UI/docsInteractive route documentation RE-DOC/redocReadable schema reference SCHEMA/openapi.jsonMachine-readable contract

11

PRODUCTION RUNTIME

Deployment

01

Bind externally

Use 0.0.0.0 inside a container or hosted runtime.

02

Proxy TLS

Terminate HTTPS at a reverse proxy or platform edge.

03

Persist media

Use a durable volume or CDN if local files must survive redeploys.

04

Probe health

Configure platform liveness checks against /healthz.

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir "fastapi[standard]" uvicorn
EXPOSE 8000
CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "8000"]

services:
  aesthetics-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      IMAGE_MODE: local
    volumes:
      - ./images:/app/images:ro

uvicorn api:app \
  --host 0.0.0.0 \
  --port "${PORT:-8000}" \
  --workers 2

12

OPERATIONS

Performance

O(1)Direct slug lookup

O(n)Substring search

~219Current record scale

GETRead-only traffic

For this dataset size, in-memory access is appropriate. Add response compression and cache headers at the reverse proxy when the full collection or remote images receive repeated public traffic.

13

DIAGNOSTICS

Troubleshooting

The explorer reports “offline” or shows sample data.＋

Confirm that Uvicorn is running, that the Base URL matches its host and port, and that browser CORS policy allows the documentation page's origin.

curl -i http://127.0.0.1:8000/healthz

The API starts but reports zero records.＋

Verify the dataset path, JSON validity, file permissions, and that the application is started from the expected working directory.

python -m json.tool aesthetics.json > /dev/null

JSON works but image endpoints return 404.＋

Check IMAGE_MODE, confirm that each record's image filename exists under IMAGE_DIR, and inspect case sensitivity on Linux hosts.

Remote images fail in a browser client.＋

The upstream host may reject hotlinking or apply its own CORS policy. Use a server-side redirect, local mirror, or controlled CDN where licensing allows it.