Ik schrijf duidelijke API-documentatie die uw ontwikkelaars vanaf dag één kunnen volgen

Waarom de meeste API-documentatie faalt

Ze beschrijven de eindpunten en slaan de delen over die mensen daadwerkelijk tegenhouden: hoe te authenticeren, hoe een realistische aanvraag eruitziet, wat de fout betekent en wat je eraan moet doen. De lezer opent dan een supportticket, wat de kosten zijn die documentatie moet wegnemen.

Hoe ik het schrijf

Van de bron, niet uit het geheugen. Ik lees de routes, de validatielaag en de foutafhandelaars, en roep vervolgens zelf de API aan met echte referenties. Elk voorbeeld in de documentatie is een aanvraag die ik heb gedaan en een respons die ik heb ontvangen — geen verzonnen payloads, geen statuscodes die het eindpunt nooit retourneert.

Wat de documentatie bevat

• Authenticatie: het verkrijgen van een token, het vernieuwen ervan en wat er gebeurt wanneer het verloopt tijdens een sessie.
• Elk eindpunt met parameters, een compleet voorbeeldverzoek en de werkelijke responsstructuur.
• Een foutreferentie die elke foutcode koppelt aan een oorzaak en een oplossing, in plaats van alleen de boodschap te herhalen.
• Een startpad dat een nieuwe ontwikkelaar in minder dan tien minuten van nul naar een succesvolle aanroep brengt.
• Rate limits, paginering, webhooks en idempotentie uitgelegd waar ze daadwerkelijk van toepassing zijn.

Formaat

Markdown in uw repository, gestructureerd voor OpenAPI of een documentatiesite — wat u ook daadwerkelijk zult onderhouden. Codevoorbeelden in de talen waar uw gebruikers naar vragen, geverifieerd door ze uit te voeren. Postman of vergelijkbare collectie inbegrepen als u er een wilt.

Wat ik nodig heb

Toegang tot de repository of het OpenAPI-bestand, één werkende referentie voor een testomgeving, en alle vragen die uw supportteam beu is te beantwoorden. Die vragen vormen de leidraad.

Niet inbegrepen

Marketingtekst. Dit documenteert precies wat de software doet; de landingspagina is een ander vak.

Doorlooptijd en communicatie

Een eerste complete conceptversie arriveert meestal binnen een week, en u beoordeelt deze aan de hand van de vragen die uw eigen supportteam blijft beantwoorden. Ik laat me liever vroeg corrigeren door de engineer die de randgevallen kent, dan iets gepolijsts en verkeerds te leveren. Elk voorbeeld in het uiteindelijke document is uitgevoerd op uw API, dus niets daarin is aspiratief.