BlueGit

projects-timfalken-com verhalenboek

Files

verhalenboek / web / docs.php

docs.php

feat: voeg Verhalenboek toe met dagen, leesvoortgang en schrijf-API
timfa project_87242033_bot_b167a9be22027ad5a4b431d0ad8426c6 · pushed by timfa · 6 weeks ago
799da657 History
docs.php 4.8 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<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>. De sleutel maakt een beheerder één keer aan onder Sleutels. Stuur <code>Accept: application/json</code> en, bij een body, <code>Content-Type: application/json</code>. Fouten zijn <code>{"error":"…"}</code> met status 401, 403, 404, 405, 409 of 422.</p>
21<h2>Dagen</h2>
22<table>
23<thead><tr><th>Methode</th><th>Pad</th><th>Wat</th></tr></thead>
24<tbody>
25<tr><td>GET</td><td><code>/days</code></td><td>Alle dagen, oudste eerst.</td></tr>
26<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>
27<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>
28<tr><td>GET</td><td><code>/days/JJJJ-MM-DD</code></td><td>Dag met verhalen, vorige en volgende bestaande dag.</td></tr>
29<tr><td>POST</td><td><code>/days</code></td><td>Maak één volledige dag met precies drie verhalen.</td></tr>
30<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>
31<tr><td>DELETE</td><td><code>/days/JJJJ-MM-DD</code></td><td>Verwijder de dag.</td></tr>
32<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>
33<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>
34<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>
35</tbody>
36</table>
37<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>
38<h2>Voorbeeld: een dag in één aanroep</h2>
39<pre><code>curl -sS -X POST \
40 -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
41 -H 'Accept: application/json' \
42 -H 'Content-Type: application/json' \
43 -d '{"date":"2026-10-05","title":"De herfstwind","stories":[
44 {"title":"Ochtend","paragraphs":["De wind stond al vroeg aan de deur."]},
45 {"title":"Middag","paragraphs":["Op het plein joeg een krant zichzelf achterna.","Iemand lachte en liep door."]},
46 {"title":"Avond","paragraphs":["Het licht in de keuken bleef aan tot de wind ging liggen."]}
47 ]}' \
48 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days'</code></pre>
49<h2>Laatste datum en gaten</h2>
50<pre><code>curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
51 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/latest'
52
53curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
54 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/gaps'</code></pre>
55<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>
56<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>
57<h2>Eén verhaal wijzigen</h2>
58<pre><code>curl -sS -X PUT \
59 -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
60 -H 'Accept: application/json' \
61 -H 'Content-Type: application/json' \
62 -d '{"title":"Middaglicht","paragraphs":["De schaduw werd korter."] }' \
63 '<?= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/2026-10-05/stories/2'</code></pre>
64<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>
65</article>
66</body>
67</html>