Bruikbare API-referentiedocumentatie

Hoe gebruikt u AI om een API te documenteren zonder het gedrag ervan te verzinnen?

1250 € per sessie, excl. btw

Samengevat

In een halve dag van 3 uur zetten de deelnemers een API-contract om in documentatie die een ontwikkelaar kan gebruiken. AI helpt om de rubrieken te structureren, toelichtingen te schrijven en voorbeelden voor te stellen, die vervolgens aan de bronnen worden getoetst. Het werk resulteert in een documentatiedossier met een controlelijst.

Waarom deze opleiding?

Onduidelijke API-documentatie dwingt integratoren te raden naar parameters, fouten en authenticatievoorwaarden. Een vlot leesbare beschrijving volstaat niet: elke aanwijzing moet overeenstemmen met het technische contract en een onderscheid maken tussen vastgesteld gedrag en ontbrekende informatie. AI vergemakkelijkt het schrijven van een eerste versie, maar kan een niet-bestaand veld, een niet-bestaande HTTP-status of een niet-bestaande regel toevoegen. De opleiding leert hoe u de voorstellen van AI begrenst op basis van de bronnen en vervolgens de juistheid ervan controleert voordat u ze in het documentatiedossier opneemt. Doorlopende casus: De fictieve organisatie Sovrane Consignes biedt een API voor het reserveren van lockers aan. Een partner moet de beschikbaarheid kunnen raadplegen, een reservering aanmaken en die annuleren. Het aangeleverde dossier omvat drie operaties, de bijbehorende JSON-schema’s, de authenticatieregels en gesimuleerde antwoorden, maar geen documentatie voor integratoren. Toepassing op het werk: Pas de structuur in de twee daaropvolgende weken toe op een echte operatie waarvoor u toestemming hebt, laat de voorbeelden nalezen door een ontwikkelaar en meet de dekking van de rubrieken en de afwijkingen van het contract. Leg de correcties vast vóór elke publicatie.

De doelstellingen van deze opleiding

  • Informatie die gedocumenteerd kan worden uit een API-contract halen.
  • Een naslagwerk per operatie en een handleiding voor het eerste gebruik structureren.
  • Met AI beschrijvingen en voorbeelden schrijven die naar de bronnen te herleiden zijn.
  • De samenhang van de gedocumenteerde verzoeken, antwoorden en fouten controleren.
  • De documentatiedekking meten en vaststellen welke informatie bevestigd moet worden.

Voor wie en met welke voorkennis?

Betrokken rollen en taken

  • Ontwikkelaars die een API toegankelijk moeten maken voor integratoren.
  • Technisch redacteurs en productverantwoordelijken die betrokken zijn bij de documentatie van interfaces.

Vereiste voorkennis

  • HTTP-methoden, statuscodes en de JSON-structuur begrijpen.
  • Al een generatieve AI-assistent gebruikt hebben voor een schrijftaak.

Waaraan u werkt

  1. Het contract en de beperkingen ervan analyseren

    Doel: Afbakenen wat zonder aannames gedocumenteerd kan worden. Referentiebronnen, operaties, schema’s, authenticatie en het onderscheid tussen ontbrekende informatie en ontbrekende functionaliteit.

  2. De referentiedocumentatie voor de operaties schrijven

    Doel: Uniforme en controleerbare rubrieken opstellen. Beschrijvingen, verplichte of optionele parameters, waardebeperkingen, HTTP-statussen en foutmeldingen.

  3. Het integratietraject uitwerken

    Doel: De operaties met elkaar verbinden in een handleiding voor het eerste gebruik. Fictieve URL, plaatsvervangend token, JSON-voorbeelden, opeenvolging van aanroepen en afhandeling van bekende fouten.

  4. Evalueren en het onderhoud voorbereiden

    Doel: De kwaliteit van het dossier vóór publicatie objectief beoordelen. Documentatiedekking, terminologische consistentie, traceerbaarheid van correcties en aanleidingen voor updates.

Wat u meeneemt

  • Matrix van bronnen, rubrieken en ontbrekende informatie.
  • Referentiedocumentatie voor de drie operaties.
  • Handleiding voor een eerste reservering met voorbeelden van verzoeken en antwoorden.
  • Ingevulde controlelijst en correctieregister.

Methode en evaluatie

  • Korte toelichtingen, onmiddellijk gevolgd door praktijkoefeningen op basis van de doorlopende casus.
  • Individueel werken en vervolgens in duo’s, waarbij deelnemers elkaars werk nalezen.
  • Begeleide gezamenlijke bespreking: wat werkt, wat moet worden gecorrigeerd en wat een menselijke beslissing blijft.
  • Voorbereiding: Zorg voor toegang tot een AI-assistent en een teksteditor die door de organisatie zijn toegestaan. Bereid een geanonimiseerd contractfragment zonder geheime informatie voor; voor de oefeningen wordt een volledig fictief dossier verstrekt.

Waarneembare criteria: De drie operaties vermelden de methode, het pad, de parameters, de eventuele body, de antwoorden en de bekende fouten. ; Elke gedocumenteerde regel verwijst naar een bron; onbekende elementen blijven expliciet aangegeven. ; De voorbeelden volgen de typen, verplichte velden en statussen van het aangeleverde contract. ; Met de handleiding kan een collega het traject reconstrueren zonder mondelinge toelichting. ; De dekking wordt berekend door het aantal volledige rubrieken te delen door het aantal verwachte rubrieken..

Veelgestelde vragen

Moet u over een toegankelijke API beschikken?

Nee. Het contract en de gesimuleerde antwoorden maken documentatiecontroles mogelijk; ze vervangen geen integratietests.

Mag u tokens aan AI doorgeven?

Nee. De voorbeelden gebruiken plaatsvervangende waarden, zonder echte identificatiegegevens of persoonsgegevens.

Wordt de documentatie tijdens de sessie gepubliceerd?

Nee. Het dossier moet nog worden gevalideerd volgens de technische goedkeuringsprocedure van de organisatie.

Wat moet u doen als het contract onvolledig is?

Geef precies aan welke informatie ontbreekt en neem contact op met de API-verantwoordelijke in plaats van AI een antwoord te laten verzinnen.

Laatst bijgewerkt: