Hoe een API voor intern gebruik documenteren

Je developer heeft zes maanden geleden een intern API gebouwd om je FileMaker-systeem met je webshop te verbinden. Het werkt prima — tot die developer met vakantie gaat, een nieuw teamlid erop voort wil bouwen, of je een externe partner wilt laten inventarisgegevens via het API pullen. Plotseling weet niemand meer welk endpoint welke velden retourneert, of datums in ISO-formaat of Nederlandse notatie staan, of wat er gebeurt als een verplicht veld ontbreekt. Het API zelf was nooit het probleem. De ontbrekende documentatie wel.

Dit artikel loopt je precies door wat intern API-documentatie moet bevatten, hoe je het structureert, en welke fouten teams stilletjes de meeste tijd kosten.

Waarom is ongedocumenteerd intern API belangrijk als alleen je eigen team het gebruikt?

"Alleen intern" wordt vaak gebruikt als excuus om documentatie over te slaan, maar interne APIs verouderen net zoals externe. Een developer die vorig jaar het endpoint voor je Exact Online-connector schreef, werkt nu aan een ander project. Een nieuwe integrator sluit zich aan om een verbinding tussen je CRM en je FileMaker-ordersysteem te bouwen, en in plaats van een spec te lezen, openen ze Postman en beginnen te gokken — testverzoeken sturen, raw JSON-responses lezen en veldnamen terugtechniseren door trial-and-error.

Dat terugontwerpen is geen eenmalige kost. Elke toekomstige integratie, elk bugrapport, elke "waarom is dit veld soms leeg"-vraag herhaalt het. Documentatie is wat een mentaal model van één persoon verandert in iets waar de hele organisatie — inclusief toekomstige medewerkers en externe contractanten — op kan vertrouwen.

Wat moet intern API-documentatie eigenlijk bevatten?

Een werkend intern API-documentatie beantwoordt minimaal deze vragen voor elk endpoint:

1. Wat doet dit endpoint in één zin? Niet "GET /orders" maar "Retourneert alle openstaande orders voor een gegeven klant, inclusief regelitems en verzendstatus."
2. Wat is de exacte URL en HTTP-methode? Neem de basis-URL voor elke omgeving op (test, staging, productie) — deze zijn bijna altijd anders, en het verwarren ervan is één van de meest voorkomende integratiefouten.
3. Welke authenticatie is vereist? API-sleutel, OAuth2-token, Basic Auth — geef aan waar die credential vandaan komt en hoe lang tokens geldig zijn.
4. Welke parameters en body-velden accepteert het? Voor elk: naam, gegevenstype, of het verplicht of optioneel is, en een echt voorbeeld-waarde — niet alleen "string" maar "orderDate": "2024-11-03" met het formaat uitgelegd.
5. Hoe ziet een succesvol antwoord eruit? Een volledig, realistisch JSON-voorbeeld, niet alleen een schemadiagram. Developers kopiëren-plakken voorbeeld-responses veel meer dan dat ze beschrijvingen per veld lezen.
6. Welke foutresponses kan het retourneren en waarom? Een 404 omdat de order niet bestaat, verschilt van een 422 omdat een verplicht veld ontbreekt. Zet de statuscodes op die jouw API werkelijk gebruikt, met een korte oorzaak voor elk.
7. Zijn er frequentielimieten, paginering of groottelimieten? Als een rapport-endpoint resultaten op 500 records per oproep limiteert, zeg dit voordat iemand een nachtelijke synchronisatie bouwt die gegevens voorbij record 500 stilletjes weggooit.
8. Is er een changelog? Ook een intern API verandert: een veld wordt hernoemd, een nieuwe verplichte parameter verschijnt. Zonder changelog verschijnen die veranderingen als productiefouten in plaats van geplande migraties.

Waar houd je intern API-documentatie?

Er is geen enkel correct hulpmiddel, maar er is wel een fout patroon: documentatie die alleen in één developer's hoofd leeft, of verspreid over Slack-threads en oude e-mailverzendingen. Drie benaderingen werken goed in de praktijk, afhankelijk van de grootte van je team en je tooling:

• Een dedicated API-documentatietool (Swagger/OpenAPI, Postman Collections, Redoc) genereert doorbladerbare, testbare docs rechtstreeks uit een specificatiebestand. Dit is de sterkste optie zodra een API meer dan een handvol endpoints heeft, omdat de docs en het werkelijke contract gekoppeld blijven — verander de spec, de docs worden bijgewerkt.
• Een actieve pagina in je interne wiki of kennisbank (Confluence, Notion, een private GitHub-wiki) werkt goed voor kleinere APIs of teams zonder dedicated API-tools. De sleuteldiscipline hier is eigenaarschap: wijs één persoon per API aan die verantwoordelijk is voor het nauwkeurig houden van de pagina.
• Inline-opmerkingen plus een README in de codebasis zelf, voor zeer kleine interne hulpprogramma's. Dit is de minimale haalbare optie — beter dan niets, maar het stort in zodra niet-developers (een business analist, een externe contractant) het moeten raadplegen zonder de code te openen.

Welke je ook kiest, de documentatie moet bereikbaar zijn voor iedereen die het nodig heeft — inclusief toekomstige teamleden die nog niet zijn ingehuurd. Een doc begraven in de persoonlijke Notion-workspace van één persoon telt niet als documentatie; het telt als een persoonlijke notitie.

Hoe documenteer je APIs die specifiek in FileMaker zijn gebouwd?

FileMaker-systemen openbaren gegevens vaak via het ingebouwde Data API, via aangepaste webpublicatie, of via een op maat gemaakte API-laag gebouwd voor een specifieke integratie — bijvoorbeeld een connector waarmee een extern warehousesysteem voorradupdates in een FileMaker-voorraadtabel kan pushen. Deze APIs zijn gemakkelijk ondergedocumenteerd omdat ze vaak werden gebouwd om één specifiek, dringend probleem op te lossen, met de aanname dat "we onthouden hoe het werkt."

Een paar FileMaker-specifieke dingen waard om expliciet vast te leggen:

• Welk FileMaker-layout of script het endpoint eigenlijk triggert, omdat Data API-oproepen typisch naar een layout-context wijzen die bepaalt welke velden zichtbaar zijn.
• Sessie- en tokenverwerking — FileMaker Data API-sessies verlopen, en ongedocumenteerde vervaldag is een klassieke bron van "het werkte gisteren"-bugrapporten.
• Enige bedrijfslogica verborgen in scripts die afvuurt bij recordcreatie of -wijziging (validatie, auto-nummering, gerelateerde recordupdates) — omdat van buiten af gezien het API er als een eenvoudige databaseschrijving uitziet, maar intern kan het verschillende afhankelijke scripts triggeren.
• Veld-specifieke eigenaardigheden: berekenningsvelden die niet rechtstreeks kunnen worden geschreven, of velden die een specifieke waarde verwachten.

Tools zoals Klai (een AI-laag die bovenop FileMaker-workflows kan zitten) of formulierbouw-lagen zoals FMBetterForms voegen een ander integratieoppervlak toe — als een van beide deel van je stack is, documenteer hoe ze van het onderliggende API lezen of erin schrijven, aangezien een wijziging in het FileMaker-schema beide stilletjes kan breken.

Welke zijn de meest voorkomende fouten bij het documenteren van interne APIs?

• Alleen het gelukkige pad documenteren. Echte integraties falen op randgevallen — ontbrekende velden, dubbele records, time-outs. Als je docs alleen succes tonen, zal je team elk foutpatroon blind tegenkomen.
• Docs laten aflopen van het werkelijke API. Een endpoint krijgt een nieuw verplicht veld, maar niemand werkt de pagina bij. Zes maanden later bouwt iemand tegen de oude spec en het breekt in productie. Behandel documentatie-updates als onderdeel van de definitie van "klaar" voor elke API-wijziging, niet als nagedachte.
• Schrijven voor de auteur, niet voor de lezer. "Retourneert het standaard order-object" betekent niets voor iemand die het standaard order-object nooit heeft gezien. Schrijf alsof de lezer nul voorkennis heeft.
• Authenticatiedetails overslaan omdat "iedereen weet hoe het werkt." Nieuwe hires en externe contractanten niet. Leg uit precies hoe je een geldige token krijgt, inclusief waar je er een aanvraagt als dat niet self-service is.
• Geen versieringsstrategie. Als je een antwoordformaat verandert, zullen oude integraties die tegen de vorige versie zijn gebouwd stilletjes breken tenzij je het endpoint versieert (bijv. /v1/orders, /v2/orders) of breaking changes duidelijk in een changelog markeert.

Een praktische checklist voordat je een intern API "gedocumenteerd" noemt

• Elk endpoint heeft een duidelijke beschrijving in begrijpelijke taal van wat het doet
• Basis-URLs staan per omgeving (test, staging, productie)
• Authenticatiemethode en token-levenscyclus worden uitgelegd
• Elke parameter heeft een naam, type, verplicht/optioneel vlag en voorbeeld-waarde
• Een volledig voorbeeld-verzoek en volledig voorbeeld-antwoord zijn opgenomen
• Veelvoorkomende foutcodes worden vermeld met hun oorzaken
• Frequentielimieten, paginering of groottelimieten worden expliciet vermeld
• Een changelog bestaat en wordt werkelijk bijgewerkt wanneer het API verandert
• Één benoemd persoon of team is verantwoordelijk voor het actueel houden van de documentatie
• De documentatie is bereikbaar voor iedereen die het nodig heeft — niet vergrendeld in één iemands inbox of notities

Veelgestelde vragen: intern API-documentatie

Heeft een puur intern API werkelijk volledige documentatie nodig, of volstaat een snelle notitie? Als meer dan één persoon het ooit zal aanraken — een collega, een opvolger, een externe contractant die voor een project wordt ingehuurd — heeft het volledige documentatie nodig. "Snelle notities" zijn prima als startconcept, niet als permanente staat.

Wie zou verantwoordelijk voor API-documentatie moeten zijn — de developer die het bouwde, of een aparte technical writer? Voor de meeste interne teams zou de developer die het endpoint bouwde de eerste concept moeten schrijven, omdat ze de randgevallen kennen. Maar eigenaarschap voor het actueel houden zou expliciet worden toegewezen, niet aan wie het onthoud.

Zouden intern API-docs openbaar binnen het bedrijf moeten zijn, of beperkt? Over het algemeen toegankelijk voor iedereen technisch in de organisatie, inclusief toekomstige hires. Beperk alleen de credentials en secrets, nooit de structuurdocumentatie zelf — docs verbergen creëert de kenniskloof die je probeert op te lossen.

Hoe hangt dit samen met integratie met externe systemen? Dezelfde documentatiediscipline is nog belangrijker zodra een API bedrijfsgrenzen overschrijdt — ons bredere stuk over hoe APIs moderne bedrijfssystemen verbinden behandelt hoe deze verbindingen op systeemniveau werken, voorbij documentatie alleen.

Als je interne APIs organisch zijn gegroeid en niemand meer precies zeker is wat elk endpoint eigenlijk doet, dat is een common — en oplosbare — fase voor een groeiende FileMaker- of ERP-omgeving. Loggix kan helpen je bestaande integraties in kaart brengen, ze correct documenteren, en waar nodig, een schoner API-laag of connector bouwen zodat je systemen, je team, en elke toekomstige developer op dezelfde gedeelde bron van waarheid kunnen vertrouwen.