API
JSON REST voor een schrijver-agent. Elke aanvraag gaat naar api.php gevolgd door het pad, bijvoorbeeld = htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days. Lokaal is het pad hetzelfde op de ontwikkelserver.
Authenticatie: Authorization: Bearer vb_…. Een beheerder maakt sleutels aan onderaan Beheer (= htmlspecialchars($base, ENT_QUOTES) ?>/#/beheer) en kan een bestaande sleutel daar opnieuw tonen. Stuur Accept: application/json en, bij een body, Content-Type: application/json. Fouten zijn JSON met status 401, 403, 404, 405, 409 of 422.
Geen of ongeldige authenticatie
Een 401 heeft de header WWW-Authenticate: Bearer. Een 401, en een 403 wanneer een lezer iets doet dat een sleutel of beheerder vereist, bevat naast error ook how_to_authenticate en dezelfde tekst in hint. Die tekst onderscheidt drie gevallen en verwijst naar deze pagina:
- Geen header. Er is geen
Authorization-header. - Verkeerd formaat. De header is geen
Bearer, of de sleutel is nietvb_plus 64 hexadecimale tekens. - Onbekend of ingetrokken. Het formaat klopt, maar de sleutel bestaat niet of is ingetrokken.
Voorbeeld bij een ontbrekende header:
{
"error": "Log in om verder te gaan.",
"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",
"hint": "…"
}
hint is dezelfde tekst als how_to_authenticate. 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.
Dagen
| Methode | Pad | Wat |
|---|---|---|
| GET | /days | Alle dagen, oudste eerst, plus week, weekDays en lastRead voor het leesoverzicht. week.previous en week.next zijn de maandag van de buurweek. hasPrevious en hasNext zijn waar als die week minstens één dagrecord heeft. ?week=JJJJ-MM-DD 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 lastRead. |
| GET | /days/latest | De nieuwste datum die nog een dagrecord heeft, ook als die onvolledig is. 404 als er nog niets is. |
| GET | /days/gaps | Ontbrekende datums tussen de eerste en de laatste dag, plus dagen met minder dan drie verhalen. |
| GET | /days/JJJJ-MM-DD | Dag met verhalen, vorige en volgende bestaande dag. |
| POST | /days | Maak één volledige dag met precies drie verhalen. |
| PUT | /days/JJJJ-MM-DD | Werk de titel bij en/of vervang alle verhalen (dan weer precies drie). |
| DELETE | /days/JJJJ-MM-DD | Verwijder de dag. |
| POST | /days/JJJJ-MM-DD/stories | Voeg een verhaal toe zolang er minder dan drie zijn. position is optioneel (1, 2 of 3). |
| PUT | /days/JJJJ-MM-DD/stories/1 | Werk titel en/of alinea's van plek 1, 2 of 3 bij. |
| DELETE | /days/JJJJ-MM-DD/stories/2 | Verwijder één verhaal. De andere plekken blijven staan, de dag wordt onvolledig. |
Een verhaal heeft een titel en minstens één alinea. De volgorde in stories wordt plek 1, 2 en 3. Een dag die al bestaat geeft 409. Een ongeldige of onvolledige dag geeft 422.
Voorbeeld: een dag in één aanroep
curl -sS -X POST \
-H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"date":"2026-10-05","title":"De herfstwind","stories":[
{"title":"Ochtend","paragraphs":["De wind stond al vroeg aan de deur."]},
{"title":"Middag","paragraphs":["Op het plein joeg een krant zichzelf achterna.","Iemand lachte en liep door."]},
{"title":"Avond","paragraphs":["Het licht in de keuken bleef aan tot de wind ging liggen."]}
]}' \
'= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days'
Laatste datum en gaten
curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
'= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/latest'
curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
'= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/gaps'
latest antwoordt met date, title, storyCount en complete. gaps antwoordt met first, latest, missing (datums zonder dag) en incomplete (datums die bestaan maar geen drie verhalen meer hebben, met missingPositions).
Staat een datum in missing, maak hem dan met POST. Staat hij in incomplete, vul de ontbrekende plek met POST /stories of vervang de dag met PUT en precies drie verhalen.
Eén verhaal wijzigen
curl -sS -X PUT \
-H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"title":"Middaglicht","paragraphs":["De schaduw werd korter."] }' \
'= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/days/2026-10-05/stories/2'
Lezers gebruiken deze sleutel niet. Hun gelezen-status hoort bij een ingelogde sessie: POST of DELETE /days/JJJJ-MM-DD/read.
Wiki
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 ## en een spatie, gevolgd door de titel. Tekst vóór het eerste hoofdstuk is de inleiding.
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. GET /me zet wiki op true of false voor die ingelogde gebruiker.
Lezen mag een ingelogde lezer en een API-sleutel. Aanmaken, wijzigen en verwijderen mag een ingelogde beheerder of dezelfde Bearer-sleutel als bij /days. Een lezer die schrijft krijgt 403, met how_to_authenticate. De sleutel hoeft geen CSRF-header te sturen. Een beheerder in de browser wel, net als bij de dagen.
| Methode | Pad | Wat |
|---|---|---|
| GET | /wiki/categories | Alle categorieën, op positie. Elke categorie bevat slug, title, position en pages (slug, titel, positie). |
| POST | /wiki/categories | Nieuwe categorie. Verplicht: title. Optioneel: slug, position. 201. |
| GET | /wiki/categories/slug | Eén categorie met haar pagina's. |
| PUT | /wiki/categories/slug | Werk titel, slug en/of positie bij. Minstens één veld. |
| DELETE | /wiki/categories/slug | Verwijder de categorie. 409 zolang er nog pagina's in staan. |
| GET | /wiki/pages | Pagina's, zonder de lopende tekst. ?q= zoekt in titel en tekst, hoofdletterongevoelig. ?category=slug beperkt tot één categorie. Beide mogen samen. |
| POST | /wiki/pages | Nieuwe pagina. Verplicht: title en category (de slug van de categorie). Optioneel: slug, content, position. 201. |
| GET | /wiki/pages/slug | Pagina met content, category en chapters. Elk hoofdstuk heeft anchor, title en blocks. |
| PUT | /wiki/pages/slug | Werk titel, slug, categorie, tekst en/of positie bij. Minstens één veld. Een lege slug wordt opnieuw uit de titel gemaakt. |
| DELETE | /wiki/pages/slug | Verwijder de pagina. |
Een slug is klein, met letters, cijfers en streepjes, bijvoorbeeld oude-plein. Ontbreekt hij, dan maakt de server hem uit de titel. nieuw, bewerken en categorie zijn gereserveerd voor pagina's; nieuw 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.
Hoofdstukken en ankers
Het anker is de slug van de hoofdstuktitel, stabiel zolang de titel en de volgorde van gelijke titels hetzelfde blijven. ## De boom wordt de-boom. Een tweede hoofdstuk met dezelfde titel wordt de-boom-2, daarna de-boom-3. De inleiding, als die er is, heeft altijd het anker inleiding. In het antwoord is title daar null.
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.
Opmaak
In de tekst van een hoofdstuk mag Markdown staan. Een regel die met ## begint blijft een hoofdstuk en wordt geen gewone kop. # of ### zonder die betekenis blijft gewone tekst.
| Schrijfwijze | Resultaat |
|---|---|
- punt of * punt | Ongeordende lijst. Het streepje of sterretje staat aan het begin van de regel, gevolgd door een spatie. |
1. punt | Genummerde lijst. Het eerste nummer bepaalt waar de telling begint. |
| twee spaties extra | Een geneste lijst. Spring minstens twee spaties verder in dan de regel erboven. Een lege regel tussen punten mag. |
**vet** of __vet__ | Vet. ***beide*** is vet én cursief. |
*cursief* of _cursief_ | Cursief. Een underscore midden in een woord, zoals foo_bar, blijft tekst. |
`code` | Code. Sterretjes en verwijzingen daarbinnen blijven letterlijk. |
> citaat | Citaat. Zet het teken aan het begin van elke regel van het citaat. |
[tekst](https://…) | Externe link. Alleen http, https en mailto (met een @) worden een link, met rel="noopener". javascript: en andere schema's blijven gewone tekst. |
Vet, cursief en code mogen door elkaar, in een lijstpunt en om een verwijzing heen. Een [[verwijzing]] in een lijstpunt of in vette tekst blijft een verwijzing. Een backslash voor een sterretje, hekje of haakje maakt dat teken letterlijk.
Verwijzingen in de tekst
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.
| Schrijfwijze | Gaat naar |
|---|---|
[[pagina-slug]] | Een andere pagina. Zonder eigen tekst wordt de paginatitel getoond. |
[[pagina-slug|tekst]] | Die pagina, met de tekst die je achter de streep zet. |
[[#hoofdstuk]] | Een hoofdstuk op dezelfde pagina. Zonder eigen tekst wordt de hoofdstuktitel getoond. |
[[#hoofdstuk|tekst]] | Dat hoofdstuk, met eigen tekst. |
[[pagina-slug#hoofdstuk]] | Een hoofdstuk op een andere pagina. |
[[pagina-slug#hoofdstuk|tekst]] | Dat hoofdstuk, met eigen tekst. |
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 "broken": true en geen page. In de app staat er „ontbreekt” achter. Een stuk als <script> of javascript: wordt gewone tekst en wordt niet uitgevoerd.
In het antwoord heeft een blok een type. Een alinea is {"type":"paragraph","inlines":[…]}. Een lijst is {"type":"list","ordered":false,"items":[{"blocks":[…]}]}; bij een genummerde lijst is ordered true en staat start erbij als de telling niet bij 1 begint. Een citaat is {"type":"quote","blocks":[…]}. Geneste lijsten zitten in de blocks van een punt.
Een tekststuk is {"type":"text","text":"…"}. Een verwijzing is {"type":"link","page":"oude-plein","anchor":"de-boom","text":"de boom","broken":false}. anchor is null als de verwijzing de hele pagina bedoelt. Vet is {"type":"strong","inlines":[…]}, cursief {"type":"em","inlines":[…]}, code {"type":"code","text":"…"} en een zichtbaar regeleinde {"type":"break"}. Een externe link is {"type":"url","href":"https://…","inlines":[…]}. Een verwijzing in het label van zo'n link wordt daar gewone tekst, zodat er geen link in een link ontstaat.
Voorbeeld
curl -sS -X POST \
-H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"title":"Plekken"}' \
'= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/wiki/categories'
curl -sS -X POST \
-H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-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]]."}' \
'= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/wiki/pages'
curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
'= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/wiki/pages?q=boom&category=plekken'
curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
'= htmlspecialchars($base, ENT_QUOTES) ?>/api.php/wiki/pages/oude-plein'
GET /wiki/pages/oude-plein geeft de hoofdstukken inleiding, de-boom en de-bank. De eerste verwijzing wijst naar hoofdstuk wie-hij-is op pagina bas. Bestaat die niet, dan is de verwijzing kapot en blijft de tekst „Bas” staan. De tweede verwijzing springt naar de-boom op dezelfde pagina.