Add API documentation and underground station importer
- Introduced a new HTML documentation page for the oradio API, including a JavaScript file to handle dynamic content and API requests. - Added a CSS file for styling the documentation page. - Implemented an underground station importer script that fetches data from Radio-Browser and writes it to a JSON file. - Created a stats module to compute and manage vote and play statistics for radio stations. - Added a polyfill for modulepreload to ensure compatibility with older browsers.
This commit is contained in:
Marco Mooren
23
web/docs/index.html
Normal file
23
web/docs/index.html
Normal file
@@ -0,0 +1,23 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>oradio · API reference</title>
|
||||
<link rel="stylesheet" href="./style.css" />
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<header class="docs-header">
|
||||
<div class="docs-header-inner">
|
||||
<a href="/" class="back">← Kiosk</a>
|
||||
<h1>oradio API</h1>
|
||||
<span class="base" id="base"></span>
|
||||
</div>
|
||||
</header>
|
||||
<main id="app"></main>
|
||||
<script type="module" src="./main.js"></script>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
241
web/docs/main.js
Normal file
241
web/docs/main.js
Normal file
@@ -0,0 +1,241 @@
|
||||
// Minimal, dependency-free API reference page for oradio.
|
||||
// Lists every public endpoint, lets the user fire a live request and inspect
|
||||
// the response. Intended as a reference companion to the kiosk.
|
||||
|
||||
const BASE = `${location.origin}/api/v1`;
|
||||
const INTERNAL = `${location.origin}/api`;
|
||||
document.getElementById('base').textContent = BASE;
|
||||
|
||||
const endpoints = [
|
||||
{
|
||||
group: 'Public (v1)',
|
||||
items: [
|
||||
{
|
||||
id: 'health',
|
||||
method: 'GET',
|
||||
path: '/health',
|
||||
summary: 'Service heartbeat plus enabled-station count.',
|
||||
tryable: true
|
||||
},
|
||||
{
|
||||
id: 'categories',
|
||||
method: 'GET',
|
||||
path: '/categories',
|
||||
summary: 'All categories with their station counts.',
|
||||
tryable: true
|
||||
},
|
||||
{
|
||||
id: 'stations-list',
|
||||
method: 'GET',
|
||||
path: '/stations',
|
||||
summary: 'Paginated station list. Filterable and sortable.',
|
||||
params: [
|
||||
{ name: 'q', desc: 'Substring filter on name / genres / country.' },
|
||||
{ name: 'category', desc: 'Category id (see /categories).' },
|
||||
{ name: 'country', desc: 'ISO country code, case-insensitive.' },
|
||||
{ name: 'genre', desc: 'Substring match against any genre.' },
|
||||
{ name: 'sort', desc: 'hot | top | plays | controversial | name (default: name).' },
|
||||
{ name: 'limit', desc: 'Max items returned (default 200, cap 1000).' }
|
||||
],
|
||||
tryable: true,
|
||||
tryQuery: 'limit=3&sort=hot'
|
||||
},
|
||||
{
|
||||
id: 'random',
|
||||
method: 'GET',
|
||||
path: '/stations/random',
|
||||
summary: 'Pick one random enabled station. Same filters as /stations. Pass redirect=stream for a 302 to the resolved audio URL.',
|
||||
params: [
|
||||
{ name: 'category', desc: 'Restrict pool to a category.' },
|
||||
{ name: 'country', desc: 'Restrict pool to a country.' },
|
||||
{ name: 'genre', desc: 'Restrict pool by genre substring.' },
|
||||
{ name: 'redirect', desc: 'Set to "stream" to 302-redirect to the resolved stream URL.' }
|
||||
],
|
||||
tryable: true,
|
||||
examples: [
|
||||
`mpv ${BASE}/stations/random?redirect=stream`,
|
||||
`curl -sLI "${BASE}/stations/random?redirect=stream" | grep -i location`
|
||||
]
|
||||
},
|
||||
{
|
||||
id: 'station',
|
||||
method: 'GET',
|
||||
path: '/stations/{uuid}',
|
||||
summary: 'Full detail for one station, including its streams.',
|
||||
params: [{ name: 'uuid', desc: 'Station UUID (see list response).' }]
|
||||
},
|
||||
{
|
||||
id: 'station-stream',
|
||||
method: 'GET',
|
||||
path: '/stations/{uuid}/stream',
|
||||
summary: '302-redirect to the resolved stream URL. Picks the highest-priority stream that was last seen up.',
|
||||
params: [
|
||||
{ name: 'uuid', desc: 'Station UUID.' },
|
||||
{ name: 'format', desc: 'Optional preferred format (mp3, aac, ogg, hls).' }
|
||||
]
|
||||
},
|
||||
{
|
||||
id: 'stream-by-uuid',
|
||||
method: 'GET',
|
||||
path: '/stations/{uuid}/streams/{streamUuid}',
|
||||
summary: 'Resolve and 302 to a specific stream. Pass redirect=0 to return JSON metadata instead.',
|
||||
params: [
|
||||
{ name: 'uuid', desc: 'Station UUID.' },
|
||||
{ name: 'streamUuid', desc: 'Stream UUID.' },
|
||||
{ name: 'redirect', desc: 'Set to "0" to return JSON instead of redirecting.' }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
group: 'Authenticated (cookie session)',
|
||||
items: [
|
||||
{
|
||||
id: 'me',
|
||||
method: 'GET',
|
||||
path: '/auth/me',
|
||||
base: INTERNAL,
|
||||
summary: 'Current signed-in user, or 401.',
|
||||
tryable: true
|
||||
},
|
||||
{
|
||||
id: 'favorites',
|
||||
method: 'GET',
|
||||
path: '/me/favorites',
|
||||
base: INTERNAL,
|
||||
summary: 'Your favorites, ordered.',
|
||||
tryable: true
|
||||
},
|
||||
{
|
||||
id: 'favorites-random',
|
||||
method: 'GET',
|
||||
path: '/me/favorites/random',
|
||||
base: INTERNAL,
|
||||
summary: 'One random favorite — used by the kiosk dice button in "favorites" mode.',
|
||||
tryable: true
|
||||
},
|
||||
{
|
||||
id: 'history',
|
||||
method: 'GET',
|
||||
path: '/me/history',
|
||||
base: INTERNAL,
|
||||
summary: 'Recent play history (last 50).',
|
||||
tryable: true
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
group: 'Rate limit',
|
||||
items: [
|
||||
{
|
||||
id: 'rate',
|
||||
method: 'INFO',
|
||||
path: '120 req / minute / IP',
|
||||
summary: 'Public /api/v1 endpoints share a per-IP token bucket. Headers X-RateLimit-Limit and X-RateLimit-Remaining tell you where you stand.'
|
||||
}
|
||||
]
|
||||
}
|
||||
];
|
||||
|
||||
const app = document.getElementById('app');
|
||||
|
||||
function el(tag, attrs, ...children) {
|
||||
const n = document.createElement(tag);
|
||||
if (attrs) {
|
||||
for (const [k, v] of Object.entries(attrs)) {
|
||||
if (v == null || v === false) continue;
|
||||
if (k === 'class') n.className = v;
|
||||
else if (k.startsWith('on') && typeof v === 'function') n.addEventListener(k.slice(2).toLowerCase(), v);
|
||||
else n.setAttribute(k, v);
|
||||
}
|
||||
}
|
||||
for (const c of children) {
|
||||
if (c == null || c === false) continue;
|
||||
n.appendChild(typeof c === 'string' ? document.createTextNode(c) : c);
|
||||
}
|
||||
return n;
|
||||
}
|
||||
|
||||
function methodChip(m) {
|
||||
return el('span', { class: `m m-${m.toLowerCase()}` }, m);
|
||||
}
|
||||
|
||||
function renderEndpoint(ep) {
|
||||
const base = ep.base || BASE;
|
||||
const fullUrl = `${base}${ep.path}`;
|
||||
const card = el('article', { class: 'ep', id: ep.id });
|
||||
card.appendChild(el('header', { class: 'ep-head' },
|
||||
methodChip(ep.method),
|
||||
el('code', { class: 'ep-path' }, fullUrl)
|
||||
));
|
||||
card.appendChild(el('p', { class: 'ep-sum' }, ep.summary));
|
||||
|
||||
if (ep.params?.length) {
|
||||
const tbl = el('table', { class: 'params' },
|
||||
el('thead', {}, el('tr', {}, el('th', {}, 'Parameter'), el('th', {}, 'Description'))),
|
||||
el('tbody', {}, ...ep.params.map((p) =>
|
||||
el('tr', {}, el('td', {}, el('code', {}, p.name)), el('td', {}, p.desc))
|
||||
))
|
||||
);
|
||||
card.appendChild(tbl);
|
||||
}
|
||||
|
||||
if (ep.examples?.length) {
|
||||
card.appendChild(el('div', { class: 'examples' },
|
||||
el('div', { class: 'examples-h' }, 'Examples'),
|
||||
...ep.examples.map((e) => el('pre', {}, el('code', {}, e)))
|
||||
));
|
||||
}
|
||||
|
||||
if (ep.tryable && ep.method === 'GET') {
|
||||
const out = el('pre', { class: 'try-out' }, 'Click "Try it" to send a live request.');
|
||||
const queryInput = el('input', {
|
||||
class: 'try-q',
|
||||
type: 'text',
|
||||
placeholder: '?key=value (optional)',
|
||||
value: ep.tryQuery ? `?${ep.tryQuery}` : ''
|
||||
});
|
||||
const button = el('button', {
|
||||
class: 'try-btn',
|
||||
onClick: async () => {
|
||||
button.disabled = true;
|
||||
button.textContent = '…';
|
||||
let q = queryInput.value.trim();
|
||||
if (q && !q.startsWith('?')) q = `?${q}`;
|
||||
const url = `${fullUrl}${q}`;
|
||||
const t0 = performance.now();
|
||||
try {
|
||||
const res = await fetch(url, { credentials: 'same-origin', redirect: 'manual' });
|
||||
const ms = Math.round(performance.now() - t0);
|
||||
let body;
|
||||
if (res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400)) {
|
||||
body = `(redirect — open in new tab to follow)`;
|
||||
} else {
|
||||
const ct = res.headers.get('content-type') || '';
|
||||
body = ct.includes('json')
|
||||
? JSON.stringify(await res.json(), null, 2)
|
||||
: (await res.text()).slice(0, 4000);
|
||||
}
|
||||
out.textContent = `${res.status} ${res.statusText || ''} · ${ms} ms\n${url}\n\n${body}`;
|
||||
} catch (err) {
|
||||
out.textContent = `error: ${err.message || err}\n${url}`;
|
||||
} finally {
|
||||
button.disabled = false;
|
||||
button.textContent = 'Try it';
|
||||
}
|
||||
}
|
||||
}, 'Try it');
|
||||
const openLink = el('a', { class: 'try-open', target: '_blank', rel: 'noopener', href: fullUrl }, 'Open ↗');
|
||||
card.appendChild(el('div', { class: 'try' },
|
||||
el('div', { class: 'try-row' }, queryInput, button, openLink),
|
||||
out
|
||||
));
|
||||
}
|
||||
|
||||
return card;
|
||||
}
|
||||
|
||||
for (const group of endpoints) {
|
||||
app.appendChild(el('h2', { class: 'group' }, group.group));
|
||||
for (const ep of group.items) app.appendChild(renderEndpoint(ep));
|
||||
}
|
||||
171
web/docs/style.css
Normal file
171
web/docs/style.css
Normal file
@@ -0,0 +1,171 @@
|
||||
:root {
|
||||
--bg-0: #07080b;
|
||||
--bg-1: #0e1116;
|
||||
--bg-2: #161a22;
|
||||
--bg-3: #1f242e;
|
||||
--line: #262b36;
|
||||
--fg: #e9ecf2;
|
||||
--muted: #8a90a0;
|
||||
--muted-2: #5d6373;
|
||||
--accent: #ff7a3d;
|
||||
--accent-2: #ffb37a;
|
||||
--good: #4ec9a6;
|
||||
--bad: #ec6a6a;
|
||||
--info: #6ab7ff;
|
||||
font-family: "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
|
||||
color-scheme: dark;
|
||||
}
|
||||
|
||||
* { box-sizing: border-box; }
|
||||
html, body { margin: 0; padding: 0; background: var(--bg-0); color: var(--fg); }
|
||||
a { color: var(--accent-2); text-decoration: none; }
|
||||
a:hover { text-decoration: underline; }
|
||||
|
||||
.docs-header {
|
||||
position: sticky; top: 0; z-index: 10;
|
||||
background: rgba(7, 8, 11, 0.92);
|
||||
border-bottom: 1px solid var(--line);
|
||||
backdrop-filter: blur(8px);
|
||||
}
|
||||
.docs-header-inner {
|
||||
max-width: 980px; margin: 0 auto;
|
||||
padding: 14px 20px;
|
||||
display: flex; align-items: center; gap: 16px;
|
||||
}
|
||||
.docs-header h1 {
|
||||
margin: 0; font-size: 18px; letter-spacing: -0.01em;
|
||||
}
|
||||
.docs-header .back {
|
||||
color: var(--muted); font-size: 13px;
|
||||
padding: 6px 10px; border: 1px solid var(--line); border-radius: 8px;
|
||||
}
|
||||
.docs-header .back:hover { color: var(--fg); background: var(--bg-2); text-decoration: none; }
|
||||
.docs-header .base {
|
||||
margin-left: auto;
|
||||
font-family: ui-monospace, "SF Mono", Menlo, monospace;
|
||||
font-size: 12px; color: var(--muted);
|
||||
padding: 4px 10px; background: var(--bg-2);
|
||||
border: 1px solid var(--line); border-radius: 8px;
|
||||
}
|
||||
|
||||
#app {
|
||||
max-width: 980px; margin: 0 auto;
|
||||
padding: 24px 20px 80px;
|
||||
}
|
||||
h2.group {
|
||||
margin: 32px 0 12px;
|
||||
font-size: 13px; text-transform: uppercase; letter-spacing: 0.1em;
|
||||
color: var(--muted);
|
||||
}
|
||||
h2.group:first-child { margin-top: 0; }
|
||||
|
||||
.ep {
|
||||
background: var(--bg-1);
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 12px;
|
||||
padding: 16px;
|
||||
margin-bottom: 14px;
|
||||
}
|
||||
.ep-head {
|
||||
display: flex; align-items: center; gap: 10px;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
.ep-path {
|
||||
font-family: ui-monospace, "SF Mono", Menlo, monospace;
|
||||
font-size: 13px; color: var(--fg);
|
||||
background: var(--bg-2);
|
||||
padding: 4px 10px; border-radius: 6px;
|
||||
border: 1px solid var(--line);
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
.ep-sum {
|
||||
margin: 10px 0 0; color: var(--muted);
|
||||
font-size: 14px; line-height: 1.5;
|
||||
}
|
||||
|
||||
.m {
|
||||
display: inline-block;
|
||||
font-size: 11px; font-weight: 800; letter-spacing: 0.06em;
|
||||
padding: 4px 8px; border-radius: 6px;
|
||||
color: #07080b;
|
||||
}
|
||||
.m-get { background: var(--good); }
|
||||
.m-post { background: var(--accent); }
|
||||
.m-put { background: #d9b14a; }
|
||||
.m-delete { background: var(--bad); color: #fff; }
|
||||
.m-info { background: var(--info); }
|
||||
|
||||
.params {
|
||||
width: 100%; border-collapse: collapse;
|
||||
margin-top: 14px;
|
||||
font-size: 13px;
|
||||
}
|
||||
.params th {
|
||||
text-align: left; font-weight: 600; color: var(--muted);
|
||||
text-transform: uppercase; font-size: 11px; letter-spacing: 0.06em;
|
||||
padding: 8px 10px; border-bottom: 1px solid var(--line);
|
||||
}
|
||||
.params td {
|
||||
padding: 8px 10px; border-bottom: 1px solid var(--line);
|
||||
color: var(--fg);
|
||||
}
|
||||
.params td:first-child { width: 160px; }
|
||||
.params code {
|
||||
font-family: ui-monospace, "SF Mono", Menlo, monospace;
|
||||
font-size: 12px; color: var(--accent-2);
|
||||
background: var(--bg-2);
|
||||
padding: 2px 6px; border-radius: 4px;
|
||||
}
|
||||
|
||||
.examples { margin-top: 14px; }
|
||||
.examples-h {
|
||||
font-size: 11px; color: var(--muted);
|
||||
text-transform: uppercase; letter-spacing: 0.06em;
|
||||
margin-bottom: 6px;
|
||||
}
|
||||
.examples pre {
|
||||
margin: 0 0 8px; padding: 10px 12px;
|
||||
background: var(--bg-0); border: 1px solid var(--line);
|
||||
border-radius: 8px;
|
||||
font-family: ui-monospace, "SF Mono", Menlo, monospace;
|
||||
font-size: 12.5px; color: var(--accent-2);
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
.try { margin-top: 14px; }
|
||||
.try-row {
|
||||
display: flex; gap: 8px; align-items: center;
|
||||
margin-bottom: 8px;
|
||||
}
|
||||
.try-q {
|
||||
flex: 1;
|
||||
background: var(--bg-2); color: var(--fg);
|
||||
border: 1px solid var(--line); border-radius: 8px;
|
||||
padding: 8px 12px; font-size: 13px;
|
||||
font-family: ui-monospace, "SF Mono", Menlo, monospace;
|
||||
outline: none;
|
||||
}
|
||||
.try-q:focus { border-color: var(--accent); }
|
||||
.try-btn {
|
||||
background: var(--accent); color: #1a0a00;
|
||||
border: 0; border-radius: 8px;
|
||||
padding: 8px 16px; font-size: 13px; font-weight: 700;
|
||||
cursor: pointer;
|
||||
font-family: inherit;
|
||||
}
|
||||
.try-btn:hover { background: #ff8a55; }
|
||||
.try-btn:disabled { opacity: 0.6; cursor: default; }
|
||||
.try-open {
|
||||
color: var(--muted); font-size: 12px;
|
||||
padding: 6px 10px; border: 1px solid var(--line); border-radius: 8px;
|
||||
}
|
||||
.try-open:hover { color: var(--fg); background: var(--bg-2); text-decoration: none; }
|
||||
.try-out {
|
||||
margin: 0; padding: 12px;
|
||||
background: var(--bg-0); border: 1px solid var(--line);
|
||||
border-radius: 8px;
|
||||
font-family: ui-monospace, "SF Mono", Menlo, monospace;
|
||||
font-size: 12px; color: var(--fg);
|
||||
max-height: 320px; overflow: auto;
|
||||
white-space: pre-wrap; word-break: break-word;
|
||||
}
|
||||
Reference in New Issue
Block a user