Page documentation API /docs.html avec TOC sticky + exemples curl + responses
This commit is contained in:
unfr
296
public/docs.html
Normal file
296
public/docs.html
Normal 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&q=<tmdb_id></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&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&q=<tmdb_id></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&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&q=<imdb_id></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&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&type=<movie|tv>&q=<tmdb_id></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&type=movie&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&q=<requête></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&q=Inception%202010'
|
||||
curl 'https://tmdb.uklm.xyz/api?t=search&q=Mr.Robot.S01E02'
|
||||
curl 'https://tmdb.uklm.xyz/api?t=search&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&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=<requête></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=<id>"}
|
||||
{"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>
|
||||
Reference in New Issue
Block a user