APIreferentie

Een APIreferentie is een formeel onderdeel van de technische documentatie van een API. Het beschrijft hoe ontwikkelaars de API kunnen gebruiken, welke eindpunten er zijn, welke parameters vereist zijn, wat de verwachte verzoek- en antwoordformaten zijn, en welke foutmeldingen kunnen optreden.

Inhoud omvat basis-URL, authenticatie en toegangsrechten, en rate limiting. Per eindpunt worden de resources beschreven met de gebruikte HTTP-methoden (GET, POST, PUT, PATCH, DELETE), padparameters, queryparameters en bodypayloads. Daarnaast worden datamodellen en schemas (bijv. JSON) gespecificeerd, samen met velden, types en verplichtingen. Voorbeelden van verzoeken en responses helpen bij de implementatie, evenals validatie-regels en foutcodes.

Technisch gezien variëren API's: RESTful API's benutten meerdere eindpunten; GraphQL biedt een enkele eindpunt met queries, mutations en schemas; er bestaan ook SOAP en gRPC als alternatieven. In een APIreferentie staan doorgaans per eindpunt details en voorbeelden.

Versiebeheer en onderhoud: versie-informatie wordt vaak in de URL of headers geplaatst. Deprecatiebeleid, migratiepaden en een changelog geven aan wat verandert en wanneer.

Gebruik en integratie: authenticatiemethoden zoals API-sleutels of OAuth, rate limits, en sandbox-omgevingen ondersteunen testen. Veel referenties bieden SDK's, curl-voorbeelden en clientbibliotheken.

Schrijf- en onderhoudsprincipes: duidelijke definities, consistente terminologie, duidelijke foutmeldingen en consistente naamgeving van endpoints dragen bij aan bruikbaarheid en onderhoudbaarheid.