API-documentatie lezen met AI

Een endpointvermelding bevat de URL, de HTTP-methode, verplichte en optionele parameters en een voorbeeldantwoord. Deze vier onderdelen heb je allemaal nodig om het endpoint aan te roepen.

Als een vermelding ingewikkeld oogt, plak je die in je assistent en vraag je om elk onderdeel te labelen, zodat de structuur in één oogopslag duidelijk wordt.

Parameters passen een verzoek aan. Verplichte parameters moeten aanwezig zijn, anders mislukt de aanroep; optionele parameters veranderen het resultaat, bijvoorbeeld de paginagrootte of taal.

In de documentatie staat meestal aangegeven welke parameters verplicht zijn. Vraag je assistent eerst alleen de verplichte parameters op te sommen, zodat je een basisaanroep werkend krijgt voordat je extra's toevoegt.

In de documentatie staat altijd beschreven hoe je je identiteit verifieert. Bij sommige API's zet je een API-sleutel in een header, bij andere gebruik je een token of queryparameter. Doe je dit niet goed, dan geeft elke aanroep de status 401 terug.

Deze sectie is gemakkelijk over het hoofd te zien. Vraag je assistent om exact de naam van de header of parameter op te halen die je verzoeken moeten bevatten.

In de documentatie staan voorbeeldantwoorden, zodat je vóór het aanroepen weet hoe de gegevens zijn opgebouwd. Zo zie je welke velden bestaan en hoe ze genest zijn.

Als je de structuur kent, kun je je code plannen. Je kunt je assistent vragen het voorbeeld te koppelen aan de exacte variabelen die op je scherm moeten worden weergegeven.

API's veranderen in de loop der tijd, dus de documentatie heeft versies, zoals v1 of 2024-01-01. Als je een voorbeeld uit een oude versie gebruikt met een nieuw endpoint, ontstaan er afwijkingen.

Controleer of je de versie leest die overeenkomt met de URL die je aanroept. Je assistent kan aangeven wanneer een voorbeeld verouderd lijkt voor het endpoint dat je gebruikt.

Veel documentatie biedt een interactieve console met "uitproberen", waarin je parameters invoert en vanuit de browser een echte aanroep uitvoert. Dit is de snelste manier om te controleren of een verzoek werkt.

Gebruik deze console om parameters te valideren voordat je code schrijft. Vraag je assistent daarna om de werkende consoleaanroep om te zetten naar de taal van je app.

List-endpoints geven zelden alles in één keer terug. Ze gebruiken paginering: je krijgt één pagina tegelijk, plus een token of paginanummer voor de volgende reeks.

In de documentatie staat uitgelegd hoe de paginering werkt. Vraag je assistent die uitleg te lezen en een kleine lus te schrijven die veilig alle pagina's ophaalt zonder de limieten voor aanroepen te overschrijden.

De echte kracht zit in het rechtstreeks aan je assistent geven van documentatie en vragen om werkende code met opmerkingen. Zo sla je het uitproberen en fouten maken over.

Vermeld altijd de link naar de documentatie of de geplakte tekst, je programmeertaal en je doel. Specifieke context levert veel vaker code op die meteen werkt.

AI kan documentatie verkeerd lezen of een parameter veronderstellen. Voer de gegenereerde aanroep altijd uit en vergelijk het resultaat met het voorbeeldantwoord in de documentatie.

Als er iets niet klopt, plak je de fout en het relevante gedeelte van de documentatie opnieuw in je assistent. Door met bewijsmateriaal te itereren, los je integratiefouten snel op.

In documentatie vind je endpoints, parameters, verificatie, voorbeeldantwoorden, versies en paginering. Begin met de snelstart en ga daarna dieper in op de vermelding die je nodig hebt.

Geef secties aan je AI-assistent voor samenvattingen in duidelijke taal en kant-en-klare code, maar controleer die altijd aan de hand van het voorbeeldantwoord. Hierna doe je een echte eerste aanroep.