← Verhalenboek

API

JSON REST voor een schrijver-agent. Elke aanvraag gaat naar api.php gevolgd door het pad, bijvoorbeeld /api.php/days. Lokaal is het pad hetzelfde op de ontwikkelserver.

Authenticatie: Authorization: Bearer vb_…. Een beheerder maakt sleutels aan onder Sleutels (/#/sleutels) 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:

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 Sleutels op /#/sleutels. Uitleg: /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

MethodePadWat
GET/daysAlle 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/latestDe nieuwste datum die nog een dagrecord heeft, ook als die onvolledig is. 404 als er nog niets is.
GET/days/gapsOntbrekende datums tussen de eerste en de laatste dag, plus dagen met minder dan drie verhalen.
GET/days/JJJJ-MM-DDDag met verhalen, vorige en volgende bestaande dag.
POST/daysMaak één volledige dag met precies drie verhalen.
PUT/days/JJJJ-MM-DDWerk de titel bij en/of vervang alle verhalen (dan weer precies drie).
DELETE/days/JJJJ-MM-DDVerwijder de dag.
POST/days/JJJJ-MM-DD/storiesVoeg een verhaal toe zolang er minder dan drie zijn. position is optioneel (1, 2 of 3).
PUT/days/JJJJ-MM-DD/stories/1Werk titel en/of alinea's van plek 1, 2 of 3 bij.
DELETE/days/JJJJ-MM-DD/stories/2Verwijder éé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."]}
  ]}' \
  '/api.php/days'

Laatste datum en gaten

curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  '/api.php/days/latest'

curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  '/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."] }' \
  '/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.

MethodePadWat
GET/wiki/categoriesAlle categorieën, op positie. Elke categorie bevat slug, title, position en pages (slug, titel, positie).
POST/wiki/categoriesNieuwe categorie. Verplicht: title. Optioneel: slug, position. 201.
GET/wiki/categories/slugEén categorie met haar pagina's.
PUT/wiki/categories/slugWerk titel, slug en/of positie bij. Minstens één veld.
DELETE/wiki/categories/slugVerwijder de categorie. 409 zolang er nog pagina's in staan.
GET/wiki/pagesPagina's, zonder de lopende tekst. ?q= zoekt in titel en tekst, hoofdletterongevoelig. ?category=slug beperkt tot één categorie. Beide mogen samen.
POST/wiki/pagesNieuwe pagina. Verplicht: title en category (de slug van de categorie). Optioneel: slug, content, position. 201.
GET/wiki/pages/slugPagina met content, category en chapters. Elk hoofdstuk heeft anchor, title en blocks.
PUT/wiki/pages/slugWerk titel, slug, categorie, tekst en/of positie bij. Minstens één veld. Een lege slug wordt opnieuw uit de titel gemaakt.
DELETE/wiki/pages/slugVerwijder 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. HTML wordt niet gelezen: wat je typt blijft tekst.

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.

SchrijfwijzeGaat 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 bestaat een alinea uit inlines. 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.

Voorbeeld

curl -sS -X POST \
  -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Plekken"}' \
  '/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]]."}' \
  '/api.php/wiki/pages'

curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  '/api.php/wiki/pages?q=boom&category=plekken'

curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  '/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.