BlueGit

projects-timfalken-com verhalenboek

Files

verhalenboek / web / docs.php

docs.php

feat: render wiki Markdown and move API keys onto Beheer
timfa project_87242033_bot_b167a9be22027ad5a4b431d0ad8426c6 · pushed by timfa · 5 weeks ago
4388c66f History
docs.php 16.5 KiB Download Raw
1<?php
2declare(strict_types=1);
3require __DIR__.'/lib/bootstrap.php';
4$base = 'https://projects.timfalken.com/verhaaltjesboek';
5?>
6<!doctype html>
7<html lang="nl" data-theme="system" data-font="sans">
8<head>
9<meta charset="utf-8">
10<meta name="viewport" content="width=device-width, initial-scale=1">
11<meta name="theme-color" content="#f4efe6">
12<title>API · Verhalenboek</title>
13<?php pwaHead(); ?>
14<link rel="stylesheet" href="<?= htmlspecialchars(assetUrl('assets/app.css'), ENT_QUOTES) ?>">
15</head>
16<body>
17<article class="docs">
18<p><a href="./">← Verhalenboek</a></p>
19<h1>API</h1>
20<p>JSON REST voor een schrijver-agent. Elke aanvraag gaat naar <code>api.php</code> gevolgd door het pad, bijvoorbeeld <code><?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days</code>. Lokaal is het pad hetzelfde op de ontwikkelserver.</p>
21<p>Authenticatie: <code>Authorization: Bearer vb_…</code>. Een beheerder maakt sleutels aan onderaan Beheer (<code><?= htmlspecialchars($base, ENT_QUOTES) ?>/#/beheer</code>) en kan een bestaande sleutel daar opnieuw tonen. Stuur <code>Accept: application/json</code> en, bij een body, <code>Content-Type: application/json</code>. Fouten zijn JSON met status 401, 403, 404, 405, 409 of 422.</p>
22<h2>Geen of ongeldige authenticatie</h2>
23<p>Een 401 heeft de header <code>WWW-Authenticate: Bearer</code>. Een 401, en een 403 wanneer een lezer iets doet dat een sleutel of beheerder vereist, bevat naast <code>error</code> ook <code>how_to_authenticate</code> en dezelfde tekst in <code>hint</code>. Die tekst onderscheidt drie gevallen en verwijst naar deze pagina:</p>
24<ul>
25<li><strong>Geen header.</strong> Er is geen <code>Authorization</code>-header.</li>
26<li><strong>Verkeerd formaat.</strong> De header is geen <code>Bearer</code>, of de sleutel is niet <code>vb_</code> plus 64 hexadecimale tekens.</li>
27<li><strong>Onbekend of ingetrokken.</strong> Het formaat klopt, maar de sleutel bestaat niet of is ingetrokken.</li>
28</ul>
29<p>Voorbeeld bij een ontbrekende header:</p>
30<pre><code>{
31 "error": "Log in om verder te gaan.",
32 "how_to_authenticate": "Er is geen Authorization-header. Stuur de header Authorization: Bearer vb_… met een API-sleutel. Een beheerder maakt sleutels aan onder Beheer op <?= htmlspecialchars($base, ENT_QUOTES) ?>/#/beheer. Uitleg: <?= htmlspecialchars($base, ENT_QUOTES) ?>/docs.php",
33 "hint": "…"
34}</code></pre>
35<p><code>hint</code> is dezelfde tekst als <code>how_to_authenticate</code>. Een 403 voor een lezer die wil schrijven legt uit dat een API-sleutel of een beheerder nodig is. Sleutels beheren kan alleen in de ingelogde beheerderssessie, niet met de sleutel zelf. Een 403 door een ongeldige sessiecookie (CSRF) heeft deze uitleg niet.</p>
36<h2>Dagen</h2>
37<table>
38<thead><tr><th>Methode</th><th>Pad</th><th>Wat</th></tr></thead>
39<tbody>
40<tr><td>GET</td><td><code>/days</code></td><td>Alle dagen, oudste eerst, plus <code>week</code>, <code>weekDays</code> en <code>lastRead</code> voor het leesoverzicht. <code>week.previous</code> en <code>week.next</code> zijn de maandag van de buurweek. <code>hasPrevious</code> en <code>hasNext</code> zijn waar als die week minstens één dagrecord heeft. <code>?week=JJJJ-MM-DD</code> kiest de kalenderweek. Zonder die parameter opent een ingelogde lezer de week van de vroegste ongelezen dag; zijn alle dagen gelezen, dan de week van <code>lastRead</code>.</td></tr>
41<tr><td>GET</td><td><code>/days/latest</code></td><td>De nieuwste datum die nog een dagrecord heeft, ook als die onvolledig is. 404 als er nog niets is.</td></tr>
42<tr><td>GET</td><td><code>/days/gaps</code></td><td>Ontbrekende datums tussen de eerste en de laatste dag, plus dagen met minder dan drie verhalen.</td></tr>
43<tr><td>GET</td><td><code>/days/JJJJ-MM-DD</code></td><td>Dag met verhalen, vorige en volgende bestaande dag.</td></tr>
44<tr><td>POST</td><td><code>/days</code></td><td>Maak één volledige dag met precies drie verhalen.</td></tr>
45<tr><td>PUT</td><td><code>/days/JJJJ-MM-DD</code></td><td>Werk de titel bij en/of vervang alle verhalen (dan weer precies drie).</td></tr>
46<tr><td>DELETE</td><td><code>/days/JJJJ-MM-DD</code></td><td>Verwijder de dag.</td></tr>
47<tr><td>POST</td><td><code>/days/JJJJ-MM-DD/stories</code></td><td>Voeg een verhaal toe zolang er minder dan drie zijn. <code>position</code> is optioneel (1, 2 of 3).</td></tr>
48<tr><td>PUT</td><td><code>/days/JJJJ-MM-DD/stories/1</code></td><td>Werk titel en/of alinea's van plek 1, 2 of 3 bij.</td></tr>
49<tr><td>DELETE</td><td><code>/days/JJJJ-MM-DD/stories/2</code></td><td>Verwijder één verhaal. De andere plekken blijven staan, de dag wordt onvolledig.</td></tr>
50</tbody>
51</table>
52<p>Een verhaal heeft een titel en minstens één alinea. De volgorde in <code>stories</code> wordt plek 1, 2 en 3. Een dag die al bestaat geeft 409. Een ongeldige of onvolledige dag geeft 422.</p>
53<h2>Voorbeeld: een dag in één aanroep</h2>
54<pre><code>curl -sS -X POST \
55 -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
56 -H 'Accept: application/json' \
57 -H 'Content-Type: application/json' \
58 -d '{"date":"2026-10-05","title":"De herfstwind","stories":[
59 {"title":"Ochtend","paragraphs":["De wind stond al vroeg aan de deur."]},
60 {"title":"Middag","paragraphs":["Op het plein joeg een krant zichzelf achterna.","Iemand lachte en liep door."]},
61 {"title":"Avond","paragraphs":["Het licht in de keuken bleef aan tot de wind ging liggen."]}
62 ]}' \
63 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days'</code></pre>
64<h2>Laatste datum en gaten</h2>
65<pre><code>curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
66 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/latest'
67
68curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
69 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/gaps'</code></pre>
70<p><code>latest</code> antwoordt met <code>date</code>, <code>title</code>, <code>storyCount</code> en <code>complete</code>. <code>gaps</code> antwoordt met <code>first</code>, <code>latest</code>, <code>missing</code> (datums zonder dag) en <code>incomplete</code> (datums die bestaan maar geen drie verhalen meer hebben, met <code>missingPositions</code>).</p>
71<p>Staat een datum in <code>missing</code>, maak hem dan met POST. Staat hij in <code>incomplete</code>, vul de ontbrekende plek met POST <code>/stories</code> of vervang de dag met PUT en precies drie verhalen.</p>
72<h2>Eén verhaal wijzigen</h2>
73<pre><code>curl -sS -X PUT \
74 -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
75 -H 'Accept: application/json' \
76 -H 'Content-Type: application/json' \
77 -d '{"title":"Middaglicht","paragraphs":["De schaduw werd korter."] }' \
78 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/2026-10-05/stories/2'</code></pre>
79<p>Lezers gebruiken deze sleutel niet. Hun gelezen-status hoort bij een ingelogde sessie: POST of DELETE <code>/days/JJJJ-MM-DD/read</code>.</p>
80<h2>Wiki</h2>
81<p>De wiki staat in de app onder het tabblad Wiki, naast Overzicht. Pagina's horen bij een categorie, bijvoorbeeld Vriendjes, Plekken of Speeltjes. Elke pagina heeft een titel, een slug en hoofdstukken. Een hoofdstuk is een regel die begint met <code>##</code> en een spatie, gevolgd door de titel. Tekst vóór het eerste hoofdstuk is de inleiding.</p>
82<p>Een beheerder ziet het tabblad altijd, ook als er nog niets staat. Een lezer ziet het pas zodra er minstens één pagina is. Een categorie zonder pagina's telt nog niet. Is de laatste pagina weg, dan verdwijnt het tabblad weer voor lezers. <code>GET /me</code> zet <code>wiki</code> op <code>true</code> of <code>false</code> voor die ingelogde gebruiker.</p>
83<p>Lezen mag een ingelogde lezer en een API-sleutel. Aanmaken, wijzigen en verwijderen mag een ingelogde beheerder of dezelfde Bearer-sleutel als bij <code>/days</code>. Een lezer die schrijft krijgt 403, met <code>how_to_authenticate</code>. De sleutel hoeft geen CSRF-header te sturen. Een beheerder in de browser wel, net als bij de dagen.</p>
84<table>
85<thead><tr><th>Methode</th><th>Pad</th><th>Wat</th></tr></thead>
86<tbody>
87<tr><td>GET</td><td><code>/wiki/categories</code></td><td>Alle categorieën, op positie. Elke categorie bevat <code>slug</code>, <code>title</code>, <code>position</code> en <code>pages</code> (slug, titel, positie).</td></tr>
88<tr><td>POST</td><td><code>/wiki/categories</code></td><td>Nieuwe categorie. Verplicht: <code>title</code>. Optioneel: <code>slug</code>, <code>position</code>. 201.</td></tr>
89<tr><td>GET</td><td><code>/wiki/categories/slug</code></td><td>Eén categorie met haar pagina's.</td></tr>
90<tr><td>PUT</td><td><code>/wiki/categories/slug</code></td><td>Werk titel, slug en/of positie bij. Minstens één veld.</td></tr>
91<tr><td>DELETE</td><td><code>/wiki/categories/slug</code></td><td>Verwijder de categorie. 409 zolang er nog pagina's in staan.</td></tr>
92<tr><td>GET</td><td><code>/wiki/pages</code></td><td>Pagina's, zonder de lopende tekst. <code>?q=</code> zoekt in titel en tekst, hoofdletterongevoelig. <code>?category=slug</code> beperkt tot één categorie. Beide mogen samen.</td></tr>
93<tr><td>POST</td><td><code>/wiki/pages</code></td><td>Nieuwe pagina. Verplicht: <code>title</code> en <code>category</code> (de slug van de categorie). Optioneel: <code>slug</code>, <code>content</code>, <code>position</code>. 201.</td></tr>
94<tr><td>GET</td><td><code>/wiki/pages/slug</code></td><td>Pagina met <code>content</code>, <code>category</code> en <code>chapters</code>. Elk hoofdstuk heeft <code>anchor</code>, <code>title</code> en <code>blocks</code>.</td></tr>
95<tr><td>PUT</td><td><code>/wiki/pages/slug</code></td><td>Werk titel, slug, categorie, tekst en/of positie bij. Minstens één veld. Een lege <code>slug</code> wordt opnieuw uit de titel gemaakt.</td></tr>
96<tr><td>DELETE</td><td><code>/wiki/pages/slug</code></td><td>Verwijder de pagina.</td></tr>
97</tbody>
98</table>
99<p>Een slug is klein, met letters, cijfers en streepjes, bijvoorbeeld <code>oude-plein</code>. Ontbreekt hij, dan maakt de server hem uit de titel. <code>nieuw</code>, <code>bewerken</code> en <code>categorie</code> zijn gereserveerd voor pagina's; <code>nieuw</code> ook voor categorieën. Een bezette slug geeft 409. Een onbekende slug geeft 404. Een lege titel, een te lange tekst of een hoofdstuk zonder titel geeft 422.</p>
100<h3>Hoofdstukken en ankers</h3>
101<p>Het anker is de slug van de hoofdstuktitel, stabiel zolang de titel en de volgorde van gelijke titels hetzelfde blijven. <code>## De boom</code> wordt <code>de-boom</code>. Een tweede hoofdstuk met dezelfde titel wordt <code>de-boom-2</code>, daarna <code>de-boom-3</code>. De inleiding, als die er is, heeft altijd het anker <code>inleiding</code>. In het antwoord is <code>title</code> daar <code>null</code>.</p>
102<p>Alinea's scheid je met een lege regel. Een regeleinde binnen een alinea wordt een spatie, zodat een zin die je over twee regels breekt één zin blijft. Twee spaties aan het eind van een regel, of een backslash, maken wel een zichtbaar regeleinde. HTML wordt niet gelezen: wat je typt blijft tekst, ook als het op een tag lijkt.</p>
103<h3>Opmaak</h3>
104<p>In de tekst van een hoofdstuk mag Markdown staan. Een regel die met <code>##</code> begint blijft een hoofdstuk en wordt geen gewone kop. <code>#</code> of <code>###</code> zonder die betekenis blijft gewone tekst.</p>
105<table>
106<thead><tr><th>Schrijfwijze</th><th>Resultaat</th></tr></thead>
107<tbody>
108<tr><td><code>- punt</code> of <code>* punt</code></td><td>Ongeordende lijst. Het streepje of sterretje staat aan het begin van de regel, gevolgd door een spatie.</td></tr>
109<tr><td><code>1. punt</code></td><td>Genummerde lijst. Het eerste nummer bepaalt waar de telling begint.</td></tr>
110<tr><td>twee spaties extra</td><td>Een geneste lijst. Spring minstens twee spaties verder in dan de regel erboven. Een lege regel tussen punten mag.</td></tr>
111<tr><td><code>**vet**</code> of <code>__vet__</code></td><td>Vet. <code>***beide***</code> is vet én cursief.</td></tr>
112<tr><td><code>*cursief*</code> of <code>_cursief_</code></td><td>Cursief. Een underscore midden in een woord, zoals <code>foo_bar</code>, blijft tekst.</td></tr>
113<tr><td><code>`code`</code></td><td>Code. Sterretjes en verwijzingen daarbinnen blijven letterlijk.</td></tr>
114<tr><td><code>&gt; citaat</code></td><td>Citaat. Zet het teken aan het begin van elke regel van het citaat.</td></tr>
115<tr><td><code>[tekst](https://…)</code></td><td>Externe link. Alleen <code>http</code>, <code>https</code> en <code>mailto</code> (met een <code>@</code>) worden een link, met <code>rel="noopener"</code>. <code>javascript:</code> en andere schema's blijven gewone tekst.</td></tr>
116</tbody>
117</table>
118<p>Vet, cursief en code mogen door elkaar, in een lijstpunt en om een verwijzing heen. Een <code>[[verwijzing]]</code> in een lijstpunt of in vette tekst blijft een verwijzing. Een backslash voor een sterretje, hekje of haakje maakt dat teken letterlijk.</p>
119<h3>Verwijzingen in de tekst</h3>
120<p>In de tekst van een pagina schrijf je een verwijzing tussen dubbele rechte haken. Het doel is altijd een slug, geen titel. Een eigen zichtbare tekst zet je achter een staande streep. De streep en de tekst zijn optioneel.</p>
121<table>
122<thead><tr><th>Schrijfwijze</th><th>Gaat naar</th></tr></thead>
123<tbody>
124<tr><td><code>[[pagina-slug]]</code></td><td>Een andere pagina. Zonder eigen tekst wordt de paginatitel getoond.</td></tr>
125<tr><td><code>[[pagina-slug|tekst]]</code></td><td>Die pagina, met de tekst die je achter de streep zet.</td></tr>
126<tr><td><code>[[#hoofdstuk]]</code></td><td>Een hoofdstuk op dezelfde pagina. Zonder eigen tekst wordt de hoofdstuktitel getoond.</td></tr>
127<tr><td><code>[[#hoofdstuk|tekst]]</code></td><td>Dat hoofdstuk, met eigen tekst.</td></tr>
128<tr><td><code>[[pagina-slug#hoofdstuk]]</code></td><td>Een hoofdstuk op een andere pagina.</td></tr>
129<tr><td><code>[[pagina-slug#hoofdstuk|tekst]]</code></td><td>Dat hoofdstuk, met eigen tekst.</td></tr>
130</tbody>
131</table>
132<p>Een verwijzing die nergens heen wijst — onbekende pagina, onbekend anker, of een slug die niet aan het patroon voldoet — blijft in de tekst staan en is geen link. In de JSON heeft zo'n stuk <code>"broken": true</code> en geen <code>page</code>. In de app staat er „ontbreekt” achter. Een stuk als <code>&lt;script&gt;</code> of <code>javascript:</code> wordt gewone tekst en wordt niet uitgevoerd.</p>
133<p>In het antwoord heeft een blok een <code>type</code>. Een alinea is <code>{"type":"paragraph","inlines":[…]}</code>. Een lijst is <code>{"type":"list","ordered":false,"items":[{"blocks":[…]}]}</code>; bij een genummerde lijst is <code>ordered</code> <code>true</code> en staat <code>start</code> erbij als de telling niet bij 1 begint. Een citaat is <code>{"type":"quote","blocks":[…]}</code>. Geneste lijsten zitten in de <code>blocks</code> van een punt.</p>
134<p>Een tekststuk is <code>{"type":"text","text":"…"}</code>. Een verwijzing is <code>{"type":"link","page":"oude-plein","anchor":"de-boom","text":"de boom","broken":false}</code>. <code>anchor</code> is <code>null</code> als de verwijzing de hele pagina bedoelt. Vet is <code>{"type":"strong","inlines":[…]}</code>, cursief <code>{"type":"em","inlines":[…]}</code>, code <code>{"type":"code","text":"…"}</code> en een zichtbaar regeleinde <code>{"type":"break"}</code>. Een externe link is <code>{"type":"url","href":"https://…","inlines":[…]}</code>. Een verwijzing in het label van zo'n link wordt daar gewone tekst, zodat er geen link in een link ontstaat.</p>
135<h3>Voorbeeld</h3>
136<pre><code>curl -sS -X POST \
137 -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
138 -H 'Accept: application/json' \
139 -H 'Content-Type: application/json' \
140 -d '{"title":"Plekken"}' \
141 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/wiki/categories'
142
143curl -sS -X POST \
144 -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
145 -H 'Accept: application/json' \
146 -H 'Content-Type: application/json' \
147 -d '{"title":"Het oude plein","slug":"oude-plein","category":"plekken","content":"Achter de huizen.\n\n## De boom\n\nHier komt [[bas#wie-hij-is|Bas]] vaak.\n\n## De bank\n\nZie ook [[#de-boom]]."}' \
148 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/wiki/pages'
149
150curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
151 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/wiki/pages?q=boom&amp;category=plekken'
152
153curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
154 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/wiki/pages/oude-plein'</code></pre>
155<p><code>GET /wiki/pages/oude-plein</code> geeft de hoofdstukken <code>inleiding</code>, <code>de-boom</code> en <code>de-bank</code>. De eerste verwijzing wijst naar hoofdstuk <code>wie-hij-is</code> op pagina <code>bas</code>. Bestaat die niet, dan is de verwijzing kapot en blijft de tekst „Bas” staan. De tweede verwijzing springt naar <code>de-boom</code> op dezelfde pagina.</p>
156</article>
157</body>
158</html>