70 — API Referentie
Contracten tussen apps en van buiten-het-portfolio de apps in. Gegenereerd waar mogelijk (OpenAPI-specs, MCP-tool registries, JSON-schema's), met de hand bewerkt waar de generator niet bij komt.
Waar atlas (60-portfolio-atlas/) het vogelvluchtperspectief is en handleidingen (80-handleidingen/) taakgericht zijn, is referentie iets dat je raadpleegt, niet leest: je komt hier met de naam van een endpoint en vertrekt met de exacte vorm.
Wanneer wel
- Een app stelt endpoints, MCP-tools of events bloot die andere apps (of externe systemen) aanroepen
- Een gedeeld schema wordt op meer dan één plek gebruikt en heeft één canonieke definitie nodig
- Een contract is nu impliciet in code en zou veiliger zijn als het expliciet werd
Wanneer niet
- Interne types binnen één app — die blijven in die repo
- Taakgerichte "hoe gebruik ik de API"-gidsen — die zijn handleidingen (
80-handleidingen/) - Eenmalige scripts of experimenten — die hebben geen stabiele contracten
Gegenereerd vs eigen
| Gegenereerd | Eigen | |
|---|---|---|
| Bron | Zusterrepo (OpenAPI, MCP-tool registry, schema-bestanden) | Met de hand bewerkt in deze repo |
| Bijwerken | Generator opnieuw draaien | Bestand aanpassen |
| Risico op verouderen | Luid (output van generator verandert, diff is zichtbaar) | Stil (rot rustig weg) |
| Geschikt voor | Endpoint-signatures, MCP-tool parameters, schema's | Narrative: waarom dit contract, deprecation-notities, voorbeelden |
Een referentie-pagina heeft typisch een Notities-sectie (handgeschreven) en een Gegenereerd-sectie (machine-geschreven, niet bewerken tussen de markers).
Zie [[PORTFOLIO-001-overlay-geen-mirror]] voor het besluit om te genereren in plaats van te spiegelen.
Statuswaarden
| Status | Betekenis |
|---|---|
| Concept | Initiële stellage, generator nog niet op dit oppervlak gericht |
| Gegenereerd | Generator draait schoon; output is actueel |
| Verouderd | Generator heeft recent niet gedraaid; behandel met argwaan |
| Uitgefaseerd | Het oppervlak zelf is uitgefaseerd; bewaard ter historie |
Bestandspatroon
<app>-<surface>-referentie.md — bijv. databank-http-referentie.md, geoportaal-mcp-referentie.md, opdrachten-scanner-events-referentie.md, gedeelde-schemas-referentie.md.
Sjabloon
# <App> <Surface> — API Referentie
**Laatst bijgewerkt:** YYYY-MM-DD (auto-bijgewerkt voor gegenereerde secties)
**Status:** Concept | Gegenereerd | Verouderd | Uitgefaseerd
**Bron:** <link naar het spec-bestand in de zusterrepo>
## Notities
(Handgeschreven. Waarom dit oppervlak bestaat, wie het consumeert, deprecation/versionering, voorbeelden die niet in de spec zelf passen.)
## Consumers
| Consumer | Roept aan | Notities |
|---|---|---|
| | | |
## Gegenereerd
<!-- BEGIN GENERATED — niet met de hand bewerken -->
(Wordt door de generator gevuld. Endpoint-lijst, parametervormen, response-schema's, MCP-tool signatures, etc.)
<!-- END GENERATED -->
## Gerelateerd
- Atlas: [[atlas-pagina]]
- Handleiding: [[handleiding-pagina]]