Mecca API — docs · Cursed Shrine

Overview

Mecca API is a pure connector: it owns no database. It validates what the caller sends, translates it into an internal shape, and forwards it to the service that owns the data — the User Auth API for accounts and watch progress, and the Mail Service for notifications.

Base URL: https://api.cursedshrine.com/api — every route below is relative to it.

Architecture

caller
  │  *Dto      (request contract)
controller
  │
service      DTO → Entity
  │  *Entity   (internal contract)
manager      orchestration
  │
adapter      Entity → Proxy, HTTP call
  │  *Proxy    (downstream contract)
downstream service (Rust)

Each domain (auth, progress, notification) is a self-contained package with its own controller, dto, service, entity, manager, adapter and proxy classes, plus a named WebClient for its downstream.

Endpoints

Auth

POST/auth/register

Create an account. username, email and password are required; any extra JSON fields are captured and forwarded untouched.

Request

{
  "username": "gaurav",
  "email": "[email protected]",
  "password": "••••••••"
}

Response

{
  "success": true,
  "message": "...",
  "data": { "message": "user created", "id": "..." }
}

POST/auth/login

Exchange credentials for a JWT, valid for 24 hours.

Request

{
  "username": "gaurav",
  "password": "••••••••"
}

Response

{
  "success": true,
  "message": "...",
  "data": { "token": "eyJhbGciOi..." }
}

Watch progress

Cross-device resume for Shows. The token is forwarded as-is; the User Auth API verifies it. A missing Authorization header is rejected with 401.

POST/progressBearer token

Save or update the position in an episode.

Request

{
  "show": "One Piece",
  "path": "Episode 01.mkv",
  "position": 612.4,
  "duration": 1420.0,
  "finished": false
}

GET/progressBearer token

Latest episode per show for the signed-in user.

GET/progress?show={show}Bearer token

Every episode watched in one show, newest first. show is the watch key, e.g. One Piece or GOT/Season 03.

Notification

POST/notification/subscribe

Add an email subscriber through the Mail Service. name must be non-empty and email must look like an address; otherwise 400.

Request

{
  "name": "Ada",
  "email": "[email protected]"
}

Response

201 Created
{
  "success": true,
  "message": "subscriber saved"
}

Errors

All failures share one JSON shape, produced by a global exception handler. Downstream HTTP errors keep their status code and the downstream's short reason; internal hosts and paths are never included.

{
  "success": false,
  "status": 400,
  "message": "..."
}

Status	When
`400`	Missing or invalid fields
`401`	Missing bearer token, invalid credentials, or expired token
`404` / `405`	Unknown route / wrong method
`409`	Username already exists
`502`	A downstream service is unreachable
`500`	Unexpected gateway error

Source

The Mecca API repository is private. The two services it fronts are open source — see User Auth API and Mail Service.