En API er bare så god som dokumentasjonen, så sørg for at din er synlig med instruksjoner av topp kvalitet og andre viktige detaljer.

Flere organisasjoner utnytter kraften til APIer for å optimalisere virksomheten. API-er har blitt en måte å låse opp verdi og gi en ekstra tjeneste.

Til tross for deres generelle popularitet, er ikke alle APIer en suksess. Adopsjonen og bruken av et API bestemmer i stor grad suksessen. For å øke bruken, må API-en din være enkel å finne og bruke.

Den beste måten å gjøre dette på er å dokumentere API-en din i detalj. Dette inkluderer detaljering av kritiske komponenter for å gjøre dem lettere å forstå. Finn ut noen av komponentene du bør inkludere i API-dokumentasjonen.

Hva er API-dokumentasjon?

API-dokumentasjon er teknisk innhold som beskriver en API i detalj. Det er en manual som inneholder all informasjonen som kreves for å jobbe med API. Dokumentet dekker API-livssyklusen og instruksjoner om integrering og bruk av komponentene.

API-dokumentasjon dekker ressursbeskrivelser, endepunkter, metoder, forespørsler og svareksempler. Den kan også inkludere praktiske veiledninger og veiledninger som viser brukerne hvordan de integreres. Å utforske hver seksjon gir brukerne en solid forståelse av integrering og bruk av API.

instagram viewer

Redaktører som Google Docs ble en gang mye brukt for profesjonell API-dokumentasjon. I dag er det mer avanserte verktøy som Document 360, Confluence og GitHub Pages. Disse verktøyene hjelper til med å integrere tekst og kode for enklere arbeidsflyter.

1. Oversikt og formål med API

Det første trinnet i å dokumentere et API er å fortelle brukerne hva det handler om. Inkluder informasjon om typen ressurser det gir. APIer har vanligvis ulike ressurser de returnerer, slik at brukeren kan be om det de trenger.

Beskrivelsen er kort, vanligvis én til tre setninger som beskriver ressursen. Beskriv den tilgjengelige ressursen, endepunktene og metodene knyttet til hvert endepunkt. Som API-utvikler beskriver du best komponentene, funksjonaliteten og brukssaken.

Her er et eksempel på en beskrivelse av Airbnb API:

2. Autentiserings- og autorisasjonsmetoder

APIer håndterer tusenvis av forespørsler og enorme mengder data. Autentisering er en av måtene å sikre at dataene til API-en din og brukere er sikre mot hackere. API-autentisering bekrefter en brukers identitet og gir dem tilgang til ressurser.

Det er flere måter å sikre endepunktsikkerhet. De fleste API-er bruker en API-nøkkel. Dette er en streng med tegn som en bruker kan generere fra nettstedet og bruke til autentisering.

API-dokumentasjonen skal veilede brukere om hvordan de skal autentisere og autorisere deres identiteter. Følgende diagram viser Twitter API-autentiseringsinformasjon.

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

I denne delen demonstrerer du hvordan du får tilgang til ressursen. Endepunktene viser bare slutten av banen, derav navnet deres. De viser tilgang til ressursen og HTTP-metoder endepunktet samhandler med, nemlig GET, POST eller DELETE.

En ressurs har sannsynligvis en rekke endepunkter. Hver med en annen vei og metode. Endepunkter har vanligvis korte beskrivelser av formålet og et URL-mønster.

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

Ta meg? fields={fields}&access_token={access-token}

4. Forespørsels- og svarformater

Du må dokumentere forespørsels- og svarformatene slik at brukeren vet hva de kan forvente. Forespørselen er en URL fra en klient som ber om en ressurs, mens svaret er tilbakemelding fra serveren.

Følgende er en eksempelforespørsel 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. Parametere og overskrifter

Du bør også dokumentere parameterne til endepunktene dine, som er alternativer du kan sende til dem. Parametre kan være en ID eller et nummer som spesifiserer mengden eller typen data som returneres som svar.

Det finnes forskjellige typer parametere, inkludert overskrifts-, sti- og spørringsstrengparametere. Endepunktene kan inneholde ulike typer parametere.

Du kan inkludere noen parametere som HTTP-forespørselshoder. Vanligvis er disse for autentiseringsformål som en API-nøkkel. Her er et eksempel på en overskrift med API-nøkler:

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

Du inkluderer baneparametere i brødteksten til endepunktet rett på URL-en. De viser en bruker hvordan og hvor de skal plassere parametrene og hvordan svaret vil se ut. Ordene i bukseseler er parametere.

Du kan også bruke kolon eller annen syntaks for å representere baneparametere.

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

Med spørringsparametere må du sette et spørsmålstegn (?) før spørringen på et endepunkt. Skill hver parameter etter det med et og-tegnet (&). Microsoft har god dokumentasjon på Graph API.

6. Feilkoder og feilhåndtering

Noen ganger mislykkes HTTP-forespørsler, noe som kan gjøre en bruker forvirret. Inkluder forventede feilkoder i dokumentasjonen for å hjelpe brukere med å forstå feilene.

LinkedIn tilbyr standard HTTP-feilkoder for feilhåndtering:

7. Eksempel på kodebiter

Kodebiter er viktige deler av dokumentasjonen din. De viser brukerne hvordan de integrerer API-en i ulike språk og formater. Inkluder hvordan du installerer og integrerer SDK-er (programvareutviklingssett) på forskjellige språk i dokumentasjonen.

RapidAPI har gode eksempler på kodebiter for utviklere:

9. API-versjons- og endringslogger

API-versjon er en viktig del av API-design. Det sikrer levering av uavbrutt tjenester til brukerne dine. Versjonsstyring kan forbedre API med nye versjoner uten å påvirke klientapplikasjoner.

Brukere kan fortsette å bruke eldre versjoner eller migrere til avanserte i tide. Hvis det er nye endringer i loggene, inkludere dem i dokumentasjonen slik at brukerne er oppmerksomme.

Microsoft Graph API har godt dokumenterte endringslogger:

Til slutt inkluderer viktige kontakter i dokumentasjonen for støtte og tilbakemelding. Disse sikrer at brukere kan nå deg med feilrapporter og informasjon om hvordan man kan forbedre API.

Verdien av API-dokumentasjon

Hvis du bygger et API for kommersiell verdi, avgjør forbruk suksessen. Og for at brukere skal kunne konsumere API-et ditt, må de forstå det.

Dokumentasjon gir liv til et API. Den forklarer komponentene i detalj i et enkelt språk som selger verdien og bruken til brukerne. Brukere vil gjerne konsumere API-et ditt hvis de har en god utvikleropplevelse.

God dokumentasjon bidrar også til å forenkle vedlikehold og skalering av API. Team som jobber med API kan bruke dokumentasjon for å administrere den.