Merge pull request #21 from ronibhakta1/refactor/api-versionalization

refactor: update API versioning and restructure routes for cleaner organization

Author: ronibhakta1

README.md

@@ -36,9 +36,11 @@ make dev-docker       # start server — downloads models on first run
 
 Server: `http://localhost:8000` · Interactive docs: `http://localhost:8000/docs` · Demo: `http://localhost:8000/demo`
 
+**Live demo:** [speech-server.readium.org/demo](https://speech-server.readium.org/demo)
+
 **Quick test:**
 ```bash
-curl -s -X POST http://localhost:8000/v1/synthesize \
+curl -s -X POST http://localhost:8000/synthesize \
   -H 'Content-Type: application/json' \
   -d '{"text":"Hello world","voice":"urn:readium:tts:pocket:en-alba"}' \
   -o /tmp/speech.mp3 && open /tmp/speech.mp3

app/api/router.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+from app.api.routes.synthesize import router as synthesize_router
+from app.api.routes.voices import router as voices_router
+
+router = APIRouter()
+router.include_router(voices_router)
+router.include_router(synthesize_router)

app/api/v1/routes/health.py app/api/routes/health.pyapp/api/v1/routes/health.py renamed to app/api/routes/health.py

@@ -15,7 +15,6 @@ class Settings(BaseSettings):
     log_level: str = "INFO"
     host: str = "0.0.0.0"
     port: int = Field(default=8000, gt=0, le=65535)
-    api_v1_prefix: str = "/v1"
     workers: int = Field(default=1, ge=1)
     domain: str = ""
 

app/api/v1/routes/synthesize.py app/api/routes/synthesize.pyapp/api/v1/routes/synthesize.py renamed to app/api/routes/synthesize.py

@@ -6,8 +6,8 @@
 from starlette.middleware.trustedhost import TrustedHostMiddleware
 
 from app.api.errors import register_error_handlers
-from app.api.v1.router import v1_router
-from app.api.v1.routes.health import router as health_router
+from app.api.router import router
+from app.api.routes.health import router as health_router
 from app.config.settings import settings
 from app.core.concurrency import init_semaphore
 from app.core.registry import ProviderRegistry
@@ -73,7 +73,7 @@ def create_app() -> FastAPI:
     register_error_handlers(app)
 
     app.include_router(health_router)
-    app.include_router(v1_router, prefix=settings.api_v1_prefix)
+    app.include_router(router)
 
     @app.get("/demo", include_in_schema=False)
     async def demo() -> FileResponse:

app/api/v1/routes/voices.py app/api/routes/voices.pyapp/api/v1/routes/voices.py renamed to app/api/routes/voices.py

@@ -143,7 +143,7 @@
 <body>
 <span class="eyebrow">TTS API Demo</span>
 <h1>Readium Speech Server</h1>
-<p>Talks to <code>GET /v1/voices</code> and <code>POST /v1/synthesize</code> on this same origin.</p>
+<p>Talks to <code>GET /voices</code> and <code>POST /synthesize</code> on this same origin.</p>
 
 <div class="card">
   <label for="text">Utterance</label>
@@ -266,7 +266,7 @@ <h2>
 function updateCurl() {
   const body = JSON.stringify(requestBody());
   curlEl.textContent =
-    `curl -s -X POST ${location.origin}/v1/synthesize \\\n` +
+    `curl -s -X POST ${location.origin}/synthesize \\\n` +
     `  -H 'Content-Type: application/json' \\\n` +
     `  -d '${body}' \\\n` +
     `  -o speech.${boundaryEl.checked ? 'json' : formatEl.value}`;
@@ -315,7 +315,7 @@ <h2>
 genderFilterEl.addEventListener('change', renderVoiceOptions);
 
 async function loadVoices() {
-  const resp = await fetch('/v1/voices');
+  const resp = await fetch('/voices');
   allVoices = await resp.json();
   populateFilterOptions(langFilterEl, [...new Set(allVoices.map(v => v.language))].sort());
   const providers = [...new Set(allVoices.map(v => v.provider))].sort();
@@ -329,7 +329,7 @@ <h2>
   statusPillEl.style.display = 'none';
   outputEl.classList.remove('error');
   outputEl.textContent = 'Loading...';
-  const resp = await fetch('/v1/synthesize', {
+  const resp = await fetch('/synthesize', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify(requestBody()),

app/api/v1/router.py

@@ -11,8 +11,8 @@ Base path: `/`. All bodies are `application/json` unless noted.
 - [Authentication](#authentication)
 - [Errors](#errors)
 - [Health](#health)
-- [`GET /voices`](#get-v1voices)
-- [`POST /synthesize`](#post-v1synthesize)
+- [`GET /voices`](#get-voices)
+- [`POST /synthesize`](#post-synthesize)
 - [Not implemented](#not-implemented)
 
 ---
@@ -65,7 +65,7 @@ Pydantic schema errors (`422`) additionally carry an `errors` array (raw Pydanti
 
 ---
 
-## `GET /v1/voices`
+## `GET /voices`
 
 ```
 GET /voices
@@ -167,7 +167,7 @@ Only `text` and `voice` are required; everything else defaults as shown.
 | `text` | string | — | Max `MAX_TEXT_LENGTH` chars (2000 default). Rejected if empty/whitespace after trim |
 | `ssml` | bool | `false` | PocketTTS strips tags before synthesis (regex `<[^>]+>` removal) — no SSML-aware prosody |
 | `language` | string \| null | `null` | Hint only; voice resolution is by `voiceURI`, not `language` |
-| `voice` | string | — | Must exactly match a `voiceURI` from `/v1/voices`. 404 if not found |
+| `voice` | string | — | Must exactly match a `voiceURI` from `/voices`. 404 if not found |
 | `prev_utterance` / `next_utterance` | string \| null | `null` | Accepted, passed into `SynthesisParams`; PocketTTS ignores both |
 | `publication_id` | string \| null | `null` | Accepted, currently unused (reserved for future cache scoping) |
 | `boundary` | bool | `false` | `true` → JSON response with base64 audio + timing marks instead of raw binary |