Een API is slechts zo goed als zijn documentatie, dus zorg ervoor dat de jouwe vindbaar is met instructies van topkwaliteit en andere belangrijke details.

Steeds meer organisaties maken gebruik van de kracht van API's om hun bedrijf te optimaliseren. API's zijn een manier geworden om waarde te ontsluiten en een extra service te bieden.

Ondanks hun algemene populariteit is niet elke API een succes. De adoptie en het gebruik van een API bepalen voor een groot deel het succes ervan. Om de acceptatie te vergroten, moet uw API gemakkelijk te vinden en te gebruiken zijn.

De beste manier om dit te doen is door uw API in detail te documenteren. Dit omvat het detailleren van kritieke componenten om ze gemakkelijker te begrijpen te maken. Ontdek enkele van de componenten die u in uw API-documentatie moet opnemen.

Wat is API-documentatie?

API-documentatie is technische inhoud die een API in detail beschrijft. Het is een handleiding met daarin alle informatie die nodig is om met de API te werken. Het document behandelt de API-levenscyclus en instructies voor het integreren en gebruiken van de componenten ervan.

instagram viewer

API-documentatie omvat resourcebeschrijvingen, eindpunten, methoden, verzoeken en responsvoorbeelden. Het kan ook praktische handleidingen en tutorials bevatten die gebruikers laten zien hoe ze het kunnen integreren. Door elke sectie te verkennen, krijgen gebruikers een goed begrip van het integreren en gebruiken van de API.

Editors zoals Google Docs werden ooit veel gebruikt voor professionele API-documentatie. Tegenwoordig zijn er meer geavanceerde tools zoals Document 360, Confluence en GitHub Pages. Deze tools helpen tekst en code te integreren voor eenvoudigere workflows.

1. Overzicht en doel van de API

De eerste stap bij het documenteren van een API is gebruikers laten weten waar het over gaat. Voeg informatie toe over het type bronnen dat het biedt. API's hebben meestal verschillende bronnen die ze retourneren, zodat de gebruiker kan vragen wat hij nodig heeft.

De beschrijving is kort, meestal een tot drie zinnen die de bron beschrijven. Beschrijf de beschikbare bron, de eindpunten en de methoden die aan elk eindpunt zijn gekoppeld. Als API-ontwikkelaar beschrijf je het beste de componenten, functionaliteit en use case.

Hier is een voorbeeld van een beschrijving van de Airbnb API:

2. Verificatie- en autorisatiemethoden

API's verwerken duizenden verzoeken en enorme hoeveelheden gegevens. Verificatie is een van de manieren om ervoor te zorgen dat de gegevens van uw API en gebruikers beveiligd zijn tegen hackers. API-verificatie verifieert de identiteit van een gebruiker en geeft ze toegang tot bronnen.

Er zijn verschillende manieren om ervoor te zorgen eindpunt beveiliging. De meeste API's gebruiken een API-sleutel. Dit is een tekenreeks die een gebruiker van de website kan genereren en gebruiken voor authenticatie.

De API-documentatie moet gebruikers begeleiden bij het verifiëren en autoriseren van hun identiteit. Het volgende diagram toont Twitter API-authenticatie-informatie.

3. Eindpunten, URI-patronen en HTTP-methoden

Laat in deze sectie zien hoe u toegang krijgt tot de bron. De eindpunten geven alleen het einde van het pad aan, vandaar hun naam. Ze tonen toegang tot de bron en HTTP-methoden het eindpunt communiceert met, namelijk GET, POST of DELETE.

Eén resource heeft waarschijnlijk verschillende eindpunten. Elk met een ander pad en methode. Eindpunten hebben meestal een korte beschrijving van hun doel en een URL-patroon.

Het volgende codevoorbeeld toont een GET-gebruikerseindpunt op Instagram.

KRIJG /mij? fields={fields}&access_token={access-token}

4. Verzoek- en antwoordformaten

U moet de aanvraag- en antwoordformaten documenteren, zodat de gebruiker weet wat hij kan verwachten. Het verzoek is een URL van een client die om een ​​bron vraagt, terwijl het antwoord feedback van de server is.

Het volgende is een voorbeeldverzoek dat u naar de LinkedIn API kunt sturen.

KRIJGEN https://api.linkedin.com/v2/{service}/1234

En hier is een voorbeeldantwoord dat kan worden geretourneerd:

{
 "id": 1234,
 "relatedEntity": "urn: li: relatedEntity: 6789"
}

5. Parameters en kopteksten

U moet ook de parameters van uw eindpunten documenteren, dit zijn opties die u aan hen kunt doorgeven. Parameters kunnen een ID of nummer zijn dat de hoeveelheid of het type gegevens specificeert dat als reactie wordt geretourneerd.

Er zijn verschillende soorten parameters, waaronder header-, pad- en querytekenreeksparameters. De eindpunten kunnen verschillende soorten parameters bevatten.

U kunt enkele parameters opnemen als HTTP-aanvraagheaders. Meestal zijn deze voor authenticatiedoeleinden, zoals een API-sleutel. Hier is een voorbeeld van een header met API-sleutels:

koppen: {
 'X-RapidAPI-sleutel': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
 'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}

U neemt padparameters op in de hoofdtekst van het eindpunt, direct op de URL. Ze laten een gebruiker zien hoe en waar de parameters moeten worden geplaatst en hoe het antwoord zal verschijnen. De woorden tussen accolades zijn parameters.

U kunt ook dubbele punten of andere syntaxis gebruiken om padparameters weer te geven.

/service/myresource/user/{user}/bicycles/{bicycleId}

Bij queryparameters moet u een vraagteken (?) voor de query op een eindpunt plaatsen. Scheid daarna elke parameter met een ampersand (&). Microsoft heeft goede documentatie over de Graph API.

6. Foutcodes en foutafhandeling

Soms mislukken HTTP-verzoeken, waardoor een gebruiker in de war kan raken. Neem verwachte foutcodes op in de documentatie om gebruikers te helpen de fouten te begrijpen.

LinkedIn biedt standaard HTTP-foutcodes voor foutafhandeling:

7. Voorbeeld codefragmenten

Codefragmenten zijn essentiële onderdelen van uw documentatie. Ze laten gebruikers zien hoe ze de API in verschillende talen en formaten kunnen integreren. Neem in de documentatie op hoe u SDK's (software development kits) in verschillende talen installeert en integreert.

RapidAPI heeft goede voorbeelden van codefragmenten voor ontwikkelaars:

9. API-versiebeheer en wijzigingslogboeken

API-versiebeheer is een essentieel onderdeel van de API-ontwerp. Het zorgt voor de levering van ononderbroken services aan uw gebruikers. Versiebeheer kan de API verbeteren met nieuwe versies zonder clienttoepassingen te beïnvloeden.

Gebruikers kunnen oudere versies blijven gebruiken of op tijd migreren naar geavanceerde versies. Als er nieuwe wijzigingen in de logboeken zijn, neem deze dan op in de documentatie zodat gebruikers hiervan op de hoogte zijn.

Microsoft Graph API heeft goed gedocumenteerde wijzigingslogboeken:

Neem ten slotte belangrijke contacten op in de documentatie voor ondersteuning en feedback. Deze zorgen ervoor dat gebruikers u kunnen bereiken met foutmeldingen en informatie over hoe de API kan worden verbeterd.

De waarde van API-documentatie

Als u een API bouwt voor commerciële waarde, bepaalt het verbruik het succes ervan. En als gebruikers uw API willen gebruiken, moeten ze deze begrijpen.

Documentatie brengt een API tot leven. Het legt de componenten in detail uit in eenvoudige taal die de waarde en het gebruik ervan aan gebruikers verkoopt. Gebruikers zullen uw API graag gebruiken als ze een geweldige ontwikkelaarservaring hebben.

Goede documentatie helpt ook om het onderhoud en de schaalbaarheid van de API te vereenvoudigen. Teams die met de API werken, kunnen documentatie gebruiken om deze te beheren.