← 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.
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.