UNFR/proxy_tmdb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Page documentation API /docs.html avec TOC sticky + exemples curl + responses

Browse Source
This commit is contained in:
unfr
2026-05-01 18:55:24 +02:00
parent 54b6cc453e
commit 7cdec46c3d
3 changed files with 565 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
public/docs.css Normal file
View File

@@ -0,0 +1,268 @@
/* API documentation page — extends public/style.css. */
body {
display: grid;
grid-template-columns: 240px 1fr;
grid-template-rows: auto 1fr auto;
grid-template-areas:
"header header"
"toc main"
"footer footer";
min-height: 100vh;
}
.topbar {
grid-area: header;
}
.toc {
grid-area: toc;
}
.docs {
grid-area: main;
}
.footer {
grid-area: footer;
}
.docs-nav {
display: flex;
gap: 18px;
flex: 1;
justify-content: center;
}
.docs-nav a {
color: var(--text-muted);
font-size: 13px;
font-weight: 500;
}
.docs-nav a:hover {
color: var(--text);
text-decoration: none;
}
/* TOC sticky sidebar */
.toc {
position: sticky;
top: 60px;
align-self: start;
padding: 24px 16px 24px 24px;
font-size: 13px;
max-height: calc(100vh - 60px);
overflow-y: auto;
border-right: 1px solid var(--border);
}
.toc h4 {
margin: 0 0 10px;
text-transform: uppercase;
letter-spacing: 0.5px;
font-size: 11px;
color: var(--text-muted);
font-weight: 600;
}
.toc ul {
list-style: none;
padding: 0;
margin: 0;
}
.toc li {
margin: 4px 0;
}
.toc ul ul {
margin-left: 14px;
font-size: 12px;
}
.toc a {
color: var(--text-muted);
text-decoration: none;
display: block;
padding: 3px 8px;
border-radius: 4px;
border-left: 2px solid transparent;
}
.toc a:hover {
color: var(--text);
background: var(--bg-3);
text-decoration: none;
}
/* Main content */
.docs {
max-width: 900px;
padding: 32px 32px 80px;
}
.docs h1 {
font-size: 32px;
margin: 0 0 8px;
color: var(--text);
}
.docs h2 {
font-size: 22px;
margin: 48px 0 16px;
padding-top: 16px;
border-top: 1px solid var(--border);
color: var(--text);
}
.docs h2:first-of-type {
border-top: 0;
padding-top: 0;
}
.docs h3 {
font-size: 16px;
margin: 24px 0 10px;
color: var(--text);
}
.docs h4 {
font-size: 12px;
margin: 20px 0 8px;
text-transform: uppercase;
letter-spacing: 0.5px;
color: var(--text-muted);
font-weight: 600;
}
.docs p {
line-height: 1.65;
color: var(--text);
}
.docs .lead {
font-size: 17px;
color: var(--text-muted);
line-height: 1.5;
}
.docs ul {
line-height: 1.7;
}
.docs code {
background: var(--bg-2);
padding: 2px 6px;
border-radius: 4px;
font-family: "SF Mono", "Monaco", "Courier New", monospace;
font-size: 0.92em;
color: #e0e7ff;
}
.docs .hint {
font-size: 13px;
color: var(--text-muted);
border-left: 3px solid var(--accent-2);
padding: 8px 14px;
background: rgba(96, 165, 250, 0.06);
border-radius: 0 6px 6px 0;
margin: 12px 0;
}
/* Code blocks */
.block {
background: #020617;
border: 1px solid var(--border);
border-radius: 8px;
padding: 14px 16px;
overflow-x: auto;
margin: 10px 0;
}
.block code {
background: transparent;
padding: 0;
color: #cbd5e1;
font-size: 12.5px;
line-height: 1.6;
white-space: pre;
}
/* Endpoint cards */
.endpoint {
background: var(--bg-3);
border-radius: var(--radius);
padding: 22px 24px;
margin: 24px 0;
border: 1px solid var(--border);
scroll-margin-top: 80px;
}
.endpoint header {
display: flex;
align-items: center;
gap: 10px;
margin-bottom: 12px;
padding-bottom: 12px;
border-bottom: 1px solid var(--border);
}
.method {
display: inline-block;
padding: 4px 9px;
border-radius: 4px;
font-size: 11px;
font-weight: 700;
letter-spacing: 0.5px;
}
.method.get {
background: #1d4ed8;
color: white;
}
.method.post {
background: #047857;
color: white;
}
.path {
background: transparent;
padding: 0;
font-size: 14px;
color: var(--text);
word-break: break-all;
}
/* Param table */
.params {
width: 100%;
border-collapse: collapse;
font-size: 13px;
margin: 8px 0 14px;
}
.params th,
.params td {
padding: 8px 12px;
border-bottom: 1px solid var(--border);
text-align: left;
}
.params th {
background: var(--bg-2);
color: var(--text-muted);
font-weight: 600;
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.5px;
}
/* Footer */
.footer {
text-align: center;
padding: 16px;
color: var(--text-dim);
font-size: 12px;
border-top: 1px solid var(--border);
}
/* Sections — anchor offset for sticky topbar */
section {
scroll-margin-top: 80px;
}
@media (max-width: 900px) {
body {
grid-template-columns: 1fr;
grid-template-areas: "header" "main" "footer";
}
.toc {
display: none;
}
.docs {
padding: 24px 18px 60px;
}
.docs-nav {
display: none;
}
}

296
public/docs.html Normal file
View File

@@ -0,0 +1,296 @@
<!doctype html>
<html lang="fr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="theme-color" content="#0b1220">
<title>proxytmdb · Documentation API</title>
<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='6' fill='%2301b4e4'/%3E%3Ctext x='16' y='22' font-family='sans-serif' font-size='18' font-weight='bold' text-anchor='middle' fill='%23000'%3Et%3C/text%3E%3C/svg%3E">
<link rel="stylesheet" href="/style.css">
<link rel="stylesheet" href="/docs.css">
</head>
<body>
<header class="topbar">
<a class="brand" href="/">
<span class="brand-mark">t</span>
<span class="brand-text">proxytmdb · <span style="color:var(--text-muted)">docs</span></span>
</a>
<nav class="docs-nav">
<a href="#overview">Vue d'ensemble</a>
<a href="#endpoints">Endpoints</a>
<a href="#errors">Erreurs</a>
<a href="#limits">Quotas</a>
</nav>
<a class="nav-link" href="/">← Retour</a>
</header>
<aside class="toc">
<h4>Sur cette page</h4>
<ul>
<li><a href="#overview">Vue d'ensemble</a></li>
<li><a href="#base">URL de base</a></li>
<li><a href="#endpoints">Endpoints</a>
<ul>
<li><a href="#ep-movie">movie</a></li>
<li><a href="#ep-tv">tv</a></li>
<li><a href="#ep-imdb">imdb</a></li>
<li><a href="#ep-providers">providers</a></li>
<li><a href="#ep-search">search</a></li>
<li><a href="#ep-search-html">/search HTML</a></li>
<li><a href="#ep-health">/health</a></li>
<li><a href="#ep-metrics">/metrics</a></li>
</ul>
</li>
<li><a href="#errors">Codes d'erreur</a></li>
<li><a href="#limits">Rate limit</a></li>
<li><a href="#cors">CORS</a></li>
</ul>
</aside>
<main class="docs">
<section id="overview">
<h1>API proxytmdb</h1>
<p class="lead">Cache local TMDB enrichi des notes IMDb avec recherche par titre / année / épisode.</p>
<p>Tous les endpoints retournent du JSON (sauf <code>/search</code> qui rend du HTML pour compat avec l'ancien PHP). Aucune authentification requise — limite globale 50 requêtes/seconde par IP.</p>
</section>
<section id="base">
<h2>URL de base</h2>
<pre class="block"><code>https://tmdb.uklm.xyz</code></pre>
<p>Tous les exemples ci-dessous utilisent des chemins relatifs.</p>
</section>
<section id="endpoints">
<h2>Endpoints</h2>
<article id="ep-movie" class="endpoint">
<header>
<span class="method get">GET</span>
<code class="path">/api?t=movie&amp;q=&lt;tmdb_id&gt;</code>
</header>
<p>Retourne le détail TMDB complet d'un film + note IMDb fusionnée.</p>
<h4>Paramètres</h4>
<table class="params">
<tr><th>Param</th><th>Type</th><th>Requis</th><th>Description</th></tr>
<tr><td><code>t</code></td><td>string</td><td>oui</td><td>Doit être <code>movie</code></td></tr>
<tr><td><code>q</code></td><td>integer</td><td>oui</td><td>ID TMDB du film</td></tr>
</table>
<h4>Exemple</h4>
<pre class="block"><code>curl 'https://tmdb.uklm.xyz/api?t=movie&amp;q=27205'</code></pre>
<h4>Réponse (extrait)</h4>
<pre class="block"><code>{
"id": 27205,
"title": "Inception",
"original_title": "Inception",
"imdb_id": "tt1375666",
"release_date": "2010-07-15",
"runtime": 148,
"vote_average": 8.4,
"vote_count": 39044,
"note_imdb": "8.8",
"vote_imdb": "2809792",
"budget": 160000000,
"revenue": 839030630,
"tagline": "Votre esprit abrite la scène du crime.",
"overview": "Dom Cobb est un voleur expérimenté…",
"genres": [{"id": 28, "name": "Action"}, …],
"production_countries": [{"iso_3166_1": "US", …}],
"poster_path": "/aej3LRUga5rhgkmRP6XMFw3ejbl.jpg",
"external_ids": {…},
"credits": {…},
"images": {…},
"videos": {…},
"translations": {…}
}</code></pre>
<p class="hint">Le format complet correspond à l'objet TMDB <code>/movie/{id}?append_to_response=credits,external_ids,release_dates,translations,images,videos</code> avec <code>note_imdb</code> et <code>vote_imdb</code> ajoutés.</p>
</article>
<article id="ep-tv" class="endpoint">
<header>
<span class="method get">GET</span>
<code class="path">/api?t=tv&amp;q=&lt;tmdb_id&gt;</code>
</header>
<p>Idem pour les séries. <code>imdb_id</code> est dans <code>external_ids.imdb_id</code> pour les séries.</p>
<h4>Exemple</h4>
<pre class="block"><code>curl 'https://tmdb.uklm.xyz/api?t=tv&amp;q=1408'</code></pre>
<p>Champs supplémentaires propres aux séries : <code>seasons</code>, <code>aggregate_credits</code>, <code>first_air_date</code>, <code>last_air_date</code>, <code>name</code>, <code>original_name</code>.</p>
</article>
<article id="ep-imdb" class="endpoint">
<header>
<span class="method get">GET</span>
<code class="path">/api?t=imdb&amp;q=&lt;imdb_id&gt;</code>
</header>
<p>Lookup direct par IMDb ID. Renvoie le détail movie ou tv correspondant. Tente movie d'abord, puis tv.</p>
<h4>Paramètres</h4>
<table class="params">
<tr><th>Param</th><th>Type</th><th>Requis</th><th>Description</th></tr>
<tr><td><code>t</code></td><td>string</td><td>oui</td><td>Doit être <code>imdb</code></td></tr>
<tr><td><code>q</code></td><td>string</td><td>oui</td><td>IMDb ID au format <code>tt0133093</code></td></tr>
</table>
<h4>Exemple</h4>
<pre class="block"><code>curl 'https://tmdb.uklm.xyz/api?t=imdb&amp;q=tt0133093'
# → renvoie l'objet complet de Matrix (TMDB 603)</code></pre>
<h4>Si non trouvé</h4>
<pre class="block"><code>{"error": "IMDb id not found in local mappings"}</code></pre>
</article>
<article id="ep-providers" class="endpoint">
<header>
<span class="method get">GET</span>
<code class="path">/api?t=providers&amp;type=&lt;movie|tv&gt;&amp;q=&lt;tmdb_id&gt;</code>
</header>
<p>Watch providers JustWatch par pays (FR, US, GB, etc.) — données du endpoint TMDB <code>/watch/providers</code>.</p>
<h4>Paramètres</h4>
<table class="params">
<tr><th>Param</th><th>Type</th><th>Requis</th><th>Description</th></tr>
<tr><td><code>t</code></td><td>string</td><td>oui</td><td>Doit être <code>providers</code></td></tr>
<tr><td><code>type</code></td><td>string</td><td>oui</td><td><code>movie</code> ou <code>tv</code></td></tr>
<tr><td><code>q</code></td><td>integer</td><td>oui</td><td>ID TMDB</td></tr>
</table>
<h4>Exemple</h4>
<pre class="block"><code>curl 'https://tmdb.uklm.xyz/api?t=providers&amp;type=movie&amp;q=603'</code></pre>
<h4>Réponse</h4>
<pre class="block"><code>{
"id": 603,
"results": {
"FR": {
"link": "https://www.themoviedb.org/movie/603/watch?locale=FR",
"flatrate": [
{"provider_id": 8, "provider_name": "Netflix", "logo_path": "/…"},
…
],
"rent": [...],
"buy": [...]
},
"US": {…},
…
}
}</code></pre>
<p class="hint">Catégories possibles par pays : <code>flatrate</code> (abonnement), <code>rent</code>, <code>buy</code>, <code>free</code>, <code>ads</code>.</p>
</article>
<article id="ep-search" class="endpoint">
<header>
<span class="method get">GET</span>
<code class="path">/api?t=search&amp;q=&lt;requête&gt;</code>
</header>
<p>Recherche par titre + année + épisode. Parsing intelligent de la requête :</p>
<ul>
<li>Année extraite via regex <code>(19|20)\d{2}</code> en excluant <code>1080</code> et <code>2160</code></li>
<li>Épisode reconnu : <code>SxxExx</code>, <code>Sxx</code>, <code>partN</code>, <code>NxN</code>, <code>Exxx</code></li>
<li>Présence d'un épisode → bascule en mode <code>tv</code>, sinon <code>movie</code></li>
<li>Distance Levenshtein UTF-8 sur titres FR / EN / VO, tri par score → popularité → écart d'année</li>
</ul>
<h4>Exemples</h4>
<pre class="block"><code>curl 'https://tmdb.uklm.xyz/api?t=search&amp;q=Inception%202010'
curl 'https://tmdb.uklm.xyz/api?t=search&amp;q=Mr.Robot.S01E02'
curl 'https://tmdb.uklm.xyz/api?t=search&amp;q=Coeur%20de%20Pirate%202019'</code></pre>
<h4>Réponse</h4>
<pre class="block"><code>{
"results": [
{
"title": "Inception",
"english_title": "Inception",
"original_title": "Inception",
"years": 2010,
"poster": "https://image.tmdb.org/t/p/w200/aej3LRUga5rhgkmRP6XMFw3ejbl.jpg",
"poster_path": "/aej3LRUga5rhgkmRP6XMFw3ejbl.jpg",
"genres": "Action Science-Fiction Aventure ",
"countries": "GB US ",
"runtime": "2 h 28 min",
"imdb_id": "tt1375666",
"imdb_url": "https://www.imdb.com/title/tt1375666",
"note_imdb": 8.8,
"vote_imdb": 2809792,
"tmdb_id": 27205,
"tmdb_url": "https://www.themoviedb.org/movie/27205",
"api_url": "https://tmdb.uklm.xyz/api?t=movie&amp;q=27205",
"note_tmdb": 8.4,
"vote_tmdb": 39044,
"budget": "$160,000,000",
"revenue": "$839,030,630",
"tagline": "Votre esprit abrite la scène du crime.",
"overview": "Dom Cobb…"
},
…
]
}</code></pre>
<p class="hint">Réponses cachées en mémoire (LRU 1000 entrées, TTL 1 h). Premier appel ~1 s, suivants ~10 ms.</p>
</article>
<article id="ep-search-html" class="endpoint">
<header>
<span class="method get">GET</span>
<code class="path">/search?query=&lt;requête&gt;</code>
</header>
<p>Même recherche, mais rendue en HTML (vignettes posters + panneaux d'info inline). Compat avec l'ancien <code>search.php</code>.</p>
<pre class="block"><code>curl 'https://tmdb.uklm.xyz/search?query=Inception%202010'</code></pre>
</article>
<article id="ep-health" class="endpoint">
<header>
<span class="method get">GET</span>
<code class="path">/health</code>
</header>
<p>Liveness/readiness JSON. <code>200</code> si l'index IMDb est chargé, <code>503</code> sinon.</p>
<pre class="block"><code>{
"status": "ok",
"uptime": 86400,
"pid": 12345,
"node": "v22.18.0",
"memory_mb": 943,
"imdb_ratings": 1664245
}</code></pre>
<p class="hint">Exempté du rate limit.</p>
</article>
<article id="ep-metrics" class="endpoint">
<header>
<span class="method get">GET</span>
<code class="path">/metrics</code>
</header>
<p>Format Prometheus standard. Métriques exposées :</p>
<ul>
<li><code>http_requests_total{method, route, status}</code> — counter</li>
<li><code>http_request_duration_seconds{method, route, status}</code> — histogram</li>
<li><code>search_cache_hits_total</code>, <code>search_cache_misses_total</code></li>
<li><code>imdb_ratings_total</code>, <code>search_workers{type}</code></li>
<li>Métriques process Node par défaut (CPU, RSS, heap, event loop lag, GC)</li>
</ul>
<p class="hint">Vue humaine disponible sur <a href="/admin">/admin</a> (onglet Métriques). Exempté du rate limit.</p>
</article>
</section>
<section id="errors">
<h2>Codes d'erreur</h2>
<table class="params">
<tr><th>Code</th><th>Cas</th></tr>
<tr><td><code>200</code></td><td>OK (même si <code>{"error": "..."}</code> dans le body — voir ci-dessous)</td></tr>
<tr><td><code>429</code></td><td>Rate limit dépassé (50 req/s)</td></tr>
<tr><td><code>503</code></td><td>Service dégradé (sur <code>/health</code> uniquement)</td></tr>
</table>
<h3>Erreurs applicatives (status 200 + champ error)</h3>
<pre class="block"><code>{"error": "Year or episode not found in query"}
{"error": "Not found in localized and original titles database"}
{"error": "IMDb id not found in local mappings"}
{"error": "providers requires type=movie|tv and q=&lt;id&gt;"}
{"error": "Not found"}</code></pre>
<p class="hint">Le statut HTTP reste 200 — vérifier la présence de la clé <code>error</code> dans le JSON.</p>
</section>
<section id="limits">
<h2>Rate limit</h2>
<p>50 requêtes par seconde par IP, global tous endpoints confondus (sauf <code>/health</code> et <code>/metrics</code>). Configurable via <code>RATE_LIMIT_PER_SEC</code>.</p>
<p>En cas de dépassement, le serveur renvoie <code>429 Too Many Requests</code> avec un header <code>retry-after</code>.</p>
</section>
<section id="cors">
<h2>CORS</h2>
<p>Tous les endpoints <code>/api</code> renvoient <code>Access-Control-Allow-Origin: *</code>. Utilisable depuis n'importe quel domaine en JS browser.</p>
</section>
</main>
<footer class="footer">proxytmdb · cache local TMDB + IMDb</footer>
</body>
</html>

1
public/index.html
View File

@@ -18,6 +18,7 @@
<input id="q" type="search" name="q" placeholder="ex: Inception 2010, Mr.Robot S01E02, tt0133093…" >
<button type="submit" class="btn">Chercher</button>
</form>
<a class="nav-link" href="/docs.html">API</a>
<a class="nav-link" href="https://www.themoviedb.org/" target="_blank" rel="noopener">TMDB</a>
</header>