| 1 | <?php |
| 2 | declare(strict_types=1); |
| 3 | require __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 | <title>API · Verhalenboek</title> |
| 12 | <link rel="icon" href="<?= htmlspecialchars(assetUrl('assets/favicon.svg'), ENT_QUOTES) ?>" type="image/svg+xml"> |
| 13 | <link rel="stylesheet" href="<?= htmlspecialchars(assetUrl('assets/app.css'), ENT_QUOTES) ?>"> |
| 14 | </head> |
| 15 | <body> |
| 16 | <article class="docs"> |
| 17 | <p><a href="./">← Verhalenboek</a></p> |
| 18 | <h1>API</h1> |
| 19 | <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> |
| 20 | <p>Authenticatie: <code>Authorization: Bearer vb_…</code>. Een beheerder maakt sleutels aan onder Sleutels (<code><?= htmlspecialchars($base, ENT_QUOTES) ?>/#/sleutels</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> |
| 21 | <h2>Geen of ongeldige authenticatie</h2> |
| 22 | <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> |
| 23 | <ul> |
| 24 | <li><strong>Geen header.</strong> Er is geen <code>Authorization</code>-header.</li> |
| 25 | <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> |
| 26 | <li><strong>Onbekend of ingetrokken.</strong> Het formaat klopt, maar de sleutel bestaat niet of is ingetrokken.</li> |
| 27 | </ul> |
| 28 | <p>Voorbeeld bij een ontbrekende header:</p> |
| 29 | <pre><code>{ |
| 30 | "error": "Log in om verder te gaan.", |
| 31 | "how_to_authenticate": "Er is geen Authorization-header. Stuur de header Authorization: Bearer vb_… met een API-sleutel. Een beheerder maakt sleutels aan onder Sleutels op <?= htmlspecialchars($base, ENT_QUOTES) ?>/#/sleutels. Uitleg: <?= htmlspecialchars($base, ENT_QUOTES) ?>/docs.php", |
| 32 | "hint": "…" |
| 33 | }</code></pre> |
| 34 | <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> |
| 35 | <h2>Dagen</h2> |
| 36 | <table> |
| 37 | <thead><tr><th>Methode</th><th>Pad</th><th>Wat</th></tr></thead> |
| 38 | <tbody> |
| 39 | <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=JJJJ-MM-DD</code> kiest de kalenderweek.</td></tr> |
| 40 | <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> |
| 41 | <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> |
| 42 | <tr><td>GET</td><td><code>/days/JJJJ-MM-DD</code></td><td>Dag met verhalen, vorige en volgende bestaande dag.</td></tr> |
| 43 | <tr><td>POST</td><td><code>/days</code></td><td>Maak één volledige dag met precies drie verhalen.</td></tr> |
| 44 | <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> |
| 45 | <tr><td>DELETE</td><td><code>/days/JJJJ-MM-DD</code></td><td>Verwijder de dag.</td></tr> |
| 46 | <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> |
| 47 | <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> |
| 48 | <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> |
| 49 | </tbody> |
| 50 | </table> |
| 51 | <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> |
| 52 | <h2>Voorbeeld: een dag in één aanroep</h2> |
| 53 | <pre><code>curl -sS -X POST \ |
| 54 | -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \ |
| 55 | -H 'Accept: application/json' \ |
| 56 | -H 'Content-Type: application/json' \ |
| 57 | -d '{"date":"2026-10-05","title":"De herfstwind","stories":[ |
| 58 | {"title":"Ochtend","paragraphs":["De wind stond al vroeg aan de deur."]}, |
| 59 | {"title":"Middag","paragraphs":["Op het plein joeg een krant zichzelf achterna.","Iemand lachte en liep door."]}, |
| 60 | {"title":"Avond","paragraphs":["Het licht in de keuken bleef aan tot de wind ging liggen."]} |
| 61 | ]}' \ |
| 62 | '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days'</code></pre> |
| 63 | <h2>Laatste datum en gaten</h2> |
| 64 | <pre><code>curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \ |
| 65 | '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/latest' |
| 66 | |
| 67 | curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \ |
| 68 | '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/gaps'</code></pre> |
| 69 | <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> |
| 70 | <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> |
| 71 | <h2>Eén verhaal wijzigen</h2> |
| 72 | <pre><code>curl -sS -X PUT \ |
| 73 | -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \ |
| 74 | -H 'Accept: application/json' \ |
| 75 | -H 'Content-Type: application/json' \ |
| 76 | -d '{"title":"Middaglicht","paragraphs":["De schaduw werd korter."] }' \ |
| 77 | '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/2026-10-05/stories/2'</code></pre> |
| 78 | <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> |
| 79 | </article> |
| 80 | </body> |
| 81 | </html> |
projects-timfalken-com verhalenboek