En API er kun så god som dens dokumentation, så sørg for, at din kan findes med instruktioner i topkvalitet og andre vigtige detaljer.

Flere organisationer udnytter API'ernes kraft til at optimere deres forretning. API'er er blevet en måde at låse værdi på og give en ekstra service.

På trods af deres generelle popularitet er ikke alle API'er en succes. Vedtagelsen og brugen af ​​en API bestemmer i høj grad dens succes. For at øge adoptionen skal din API være nem at finde og bruge.

Den bedste måde at gøre dette på er ved at dokumentere din API i detaljer. Dette inkluderer detaljering af kritiske komponenter for at gøre dem nemmere at forstå. Find ud af nogle af de komponenter, du bør inkludere i din API-dokumentation.

Hvad er API-dokumentation?

API-dokumentation er teknisk indhold, der beskriver en API i detaljer. Det er en manual, der indeholder alle de nødvendige oplysninger for at arbejde med API'en. Dokumentet dækker API-livscyklussen og instruktioner om integration og brug af dets komponenter.

instagram viewer

API-dokumentation dækker ressourcebeskrivelser, slutpunkter, metoder, anmodninger og svareksempler. Det kan også omfatte praktiske vejledninger og tutorials, der viser brugerne, hvordan de integreres. Udforskning af hver sektion giver brugerne en solid forståelse af integration og brug af API.

Redaktører som Google Docs blev engang meget brugt til professionel API-dokumentation. I dag er der mere avancerede værktøjer som Document 360, Confluence og GitHub Pages. Disse værktøjer hjælper med at integrere tekst og kode for lettere arbejdsgange.

1. Oversigt og formål med API

Det første trin i at dokumentere en API er at lade brugerne vide, hvad det handler om. Inkluder oplysninger om den type ressourcer, det giver. API'er har normalt forskellige ressourcer, de returnerer, så brugeren kan anmode om, hvad de har brug for.

Beskrivelsen er kort, normalt en til tre sætninger, der beskriver ressourcen. Beskriv den tilgængelige ressource, endepunkterne og de metoder, der er knyttet til hvert endepunkt. Som API-udvikler beskriver du bedst dets komponenter, funktionalitet og use case.

Her er et eksempel på en beskrivelse af Airbnb's API:

2. Godkendelses- og autorisationsmetoder

API'er håndterer tusindvis af anmodninger og enorme mængder data. Autentificering er en af ​​måderne til at sikre, at dataene på din API og brugere er sikre mod hackere. API-godkendelse verificerer en brugers identitet og giver dem adgang til ressourcer.

Der er flere måder at sikre slutpunktssikkerhed. De fleste API'er bruger en API-nøgle. Dette er en streng af tegn, som en bruger kan generere fra webstedet og bruge til godkendelse.

API-dokumentationen skal vejlede brugere om, hvordan de godkender og autoriserer deres identiteter. Følgende diagram viser Twitter API-godkendelsesoplysninger.

3. Slutpunkter, URI-mønstre og HTTP-metoder

I dette afsnit skal du demonstrere, hvordan du får adgang til ressourcen. Endepunkterne viser kun enden af ​​stien, deraf deres navn. De viser adgang til ressourcen og HTTP metoder endepunktet interagerer med, nemlig GET, POST eller DELETE.

En ressource har sandsynligvis en række endepunkter. Hver med en anden vej og metode. Endpoints har normalt korte beskrivelser af deres formål og et URL-mønster.

Følgende kodeeksempel viser et GET-brugerslutpunkt på Instagram.

Få mig? fields={fields}&access_token={access-token}

4. Forespørgsels- og svarformater

Du skal dokumentere anmodnings- og svarformaterne, så brugeren ved, hvad han kan forvente. Anmodningen er en URL fra en klient, der beder om en ressource, mens svaret er feedback fra serveren.

Følgende er en prøveanmodning, som du kan sende til LinkedIn API.

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

Og her er et eksempelsvar, som det kan returnere:

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

5. Parametre og overskrifter

Du bør også dokumentere dine endepunkters parametre, som er muligheder, som du kan videregive til dem. Parametre kan være et ID eller nummer, der specificerer mængden eller typen af ​​data, der returneres som svar.

Der er forskellige typer parametre, herunder header-, sti- og forespørgselsstrengparametre. Endepunkterne kan indeholde forskellige typer parametre.

Du kan inkludere nogle parametre som HTTP-anmodningsheadere. Normalt er disse til autentificeringsformål som en API-nøgle. Her er et eksempel på en header med API-nøgler:

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

Du inkluderer stiparametre i endepunktets brødtekst lige på URL'en. De viser en bruger, hvordan og hvor parametrene skal placeres, og hvordan svaret vil se ud. Ordene i krøllede seler er parametre.

Du kan også bruge koloner eller anden syntaks til at repræsentere stiparametre.

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

Med forespørgselsparametre skal du placere et spørgsmålstegn (?) før forespørgslen på et slutpunkt. Adskil hver parameter efter det med et og-tegn (&). Microsoft har god dokumentation om Graph API.

6. Fejlkoder og fejlhåndtering

Nogle gange mislykkes HTTP-anmodninger, hvilket kan efterlade en bruger forvirret. Medtag forventede fejlkoder i dokumentationen for at hjælpe brugerne med at forstå fejlene.

LinkedIn leverer standard HTTP-fejlkoder til fejlhåndtering:

7. Eksempel på kodestykker

Kodestykker er væsentlige dele af din dokumentation. De viser brugerne, hvordan man integrerer API'en i forskellige sprog og formater. Inkluder, hvordan man installerer og integrerer SDK'er (softwareudviklingssæt) på forskellige sprog i dokumentationen.

RapidAPI har gode eksempler på kodestykker til udviklere:

9. API-versionering og ændringslogfiler

API-versionering er en væsentlig del af API design. Det sikrer levering af uafbrudte tjenester til dine brugere. Versionering kan forbedre API'et med nye versioner uden at påvirke klientapplikationer.

Brugere kan fortsætte med at bruge ældre versioner eller migrere til avancerede i tide. Hvis der er nye ændringer i loggene, skal du medtage dem i dokumentationen, så brugerne er opmærksomme.

Microsoft Graph API har veldokumenterede ændringslogfiler:

Medtag endelig vigtige kontakter i dokumentationen for support og feedback. Disse sikrer, at brugere kan nå dig med fejlrapporter og information om, hvordan man kan forbedre API'en.

Værdien af ​​API-dokumentation

Hvis du bygger en API til kommerciel værdi, afgør forbruget dens succes. Og for at brugerne kan bruge din API, skal de forstå den.

Dokumentation bringer en API til live. Det forklarer komponenterne i detaljer i et enkelt sprog, der sælger dens værdi og brug til brugerne. Brugere vil med glæde forbruge din API, hvis de har en god udvikleroplevelse.

God dokumentation er også med til at forenkle vedligeholdelsen og skaleringen af ​​API'et. Teams, der arbejder med API'en, kan bruge dokumentation til at administrere den.