API Reference

The API runs on port 8080 at the origin. Cloudflare Origin Rules route all /api/* traffic to this port. All responses are application/json. An Authorization header is accepted (used by API Shield as a session identifier) but not required. For API support, contact [email protected].

Base URL /api/v1
Content-Type application/json
Rate Limit 100 req/min per IP
Auth Bearer token (optional)
GET /api/v1/health

Health check. Returns a simple status object. Used by monitoring systems to verify the API is up.

Example Request

curl -s https://<domain>/api/v1/health \
  -H "Authorization: Bearer demo-token-12345"

Response 200 OK

{
  "status": "ok"
}
GET /api/v1/photos

List all photos. Returns an array of photo objects with ID, title, gallery, and URL.

Example Request

curl -s https://<domain>/api/v1/photos \
  -H "Authorization: Bearer demo-token-12345"

Response 200 OK

[
  {
    "id": 1,
    "title": "Aurora Borealis",
    "url": "/gallery/photo.php?id=1",
    "gallery": "landscapes"
  },
  ...
]
GET /api/v1/photos/:id

Get a single photo by numeric ID. Returns the full photo object including description. Returns 404 for unknown IDs.

Path Parameters

NameTypeDescription
idintegerPhoto ID (e.g. 1, 2, 5)

Example Request

curl -s https://<domain>/api/v1/photos/1 \
  -H "Authorization: Bearer demo-token-12345"

Response 200 OK

{
  "id": 1,
  "title": "Aurora Borealis",
  "url": "/gallery/photo.php?id=1",
  "description": "The northern lights dance across the Arctic sky...",
  "gallery": "landscapes"
}

Error Response 404 Not Found

{
  "error": "Photo #999 not found"
}
POST /api/v1/photos

Create a new photo. Accepts a JSON body with title (required) and description (optional). Returns the created object with a server-assigned ID. Data is stored in memory and resets on server restart.

Request Body

FieldTypeRequiredDescription
titlestringYesPhoto title
descriptionstringNoPhoto description

Example Request

curl -s -X POST https://<domain>/api/v1/photos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer demo-token-12345" \
  -d '{"title":"New Photo","description":"A test photo"}'

Response 201 Created

{
  "id": 100,
  "title": "New Photo",
  "description": "A test photo",
  "url": "/gallery/photo.php?id=100"
}

Error Response 400 Bad Request

{
  "error": "title is required"
}

Cloudflare Configuration Notes

Origin Routing
Cloudflare Origin Rules route /api/* requests to port 8080 on the origin. The API server (Express) listens on 127.0.0.1:8081, with nginx reverse-proxying :8080 → :8081.
Rate Limiting
100 requests per minute per IP. Exceeding this returns HTTP 429 with a 60-second block.
API Shield
The Authorization header is used as a session identifier for traffic analytics. The origin does not validate the token value — any Bearer <value> is accepted.
Cache
API responses follow default Cloudflare cache behaviour. GET requests to /api/v1/photos may be cached at the edge depending on response headers.
CORS
The API sets Access-Control-Allow-Origin: * on all responses. Preflight OPTIONS requests return 204.