10 Viktiga komponenter i API-dokumentation

Fler organisationer utnyttjar kraften hos API: er för att optimera sin verksamhet. API: er har blivit ett sätt att låsa upp värde och tillhandahålla en extra tjänst.

Trots deras allmänna popularitet är inte alla API en framgång. Antagandet och användningen av ett API avgör till stor del dess framgång. För att öka användningen måste ditt API vara lätt att hitta och använda.

Det bästa sättet att göra detta är genom att dokumentera ditt API i detalj. Detta inkluderar detaljer om viktiga komponenter för att göra dem lättare att förstå. Ta reda på några av komponenterna som du bör inkludera i din API-dokumentation.

Vad är API-dokumentation?

API-dokumentation är tekniskt innehåll som beskriver ett API i detalj. Det är en manual som innehåller all information som krävs för att arbeta med API: et. Dokumentet täcker API: s livscykel och instruktioner om att integrera och använda dess komponenter.

API-dokumentation täcker resursbeskrivningar, slutpunkter, metoder, förfrågningar och svarsexempel. Det kan också innehålla praktiska guider och handledningar som visar användarna hur man integrerar det. Att utforska varje avsnitt ger användarna en gedigen förståelse för att integrera och använda API: et.

Redaktörer som Google Docs användes en gång i stor utsträckning för professionell API-dokumentation. Nuförtiden finns det mer avancerade verktyg som Document 360, Confluence och GitHub Pages. Dessa verktyg hjälper till att integrera text och kod för enklare arbetsflöden.

1. Översikt och syfte med API

Det första steget i att dokumentera ett API är att låta användarna veta vad det handlar om. Inkludera information om vilken typ av resurser den tillhandahåller. API: er har vanligtvis olika resurser de returnerar, så att användaren kan begära det de behöver.

Beskrivningen är kort, vanligtvis en till tre meningar som beskriver resursen. Beskriv den tillgängliga resursen, endpoints och metoderna kopplade till varje endpoint. Som API-utvecklare beskriver du bäst dess komponenter, funktionalitet och användningsfall.

Här är ett exempel på en beskrivning av Airbnbs API:

2. Autentiserings- och auktoriseringsmetoder

API: er hanterar tusentals förfrågningar och enorma mängder data. Autentisering är ett av sätten att säkerställa att data från ditt API och användarna är säkra från hackare. API-autentisering verifierar en användares identitet och ger dem tillgång till resurser.

Det finns flera sätt att säkerställa slutpunktssäkerhet. De flesta API: er använder en API-nyckel. Detta är en teckensträng som en användare kan generera från webbplatsen och använda för autentisering.

API-dokumentationen bör vägleda användare om hur man autentiserar och auktoriserar sina identiteter. Följande diagram visar Twitter API-autentiseringsinformation.

3. Slutpunkter, URI-mönster och HTTP-metoder

I det här avsnittet visar du hur du kommer åt resursen. Slutpunkterna visar bara slutet av vägen, därav deras namn. De visar tillgång till resursen och HTTP-metoder slutpunkten interagerar med, nämligen GET, POST eller DELETE.

En resurs har sannolikt en mängd olika slutpunkter. Var och en med olika vägar och metoder. Slutpunkter har vanligtvis korta beskrivningar av sitt syfte och ett URL-mönster.

Följande kodexempel visar en GET-användarslutpunkt på Instagram.

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

4. Begäran och svarsformat

Du måste dokumentera förfrågnings- och svarsformaten så att användaren vet vad som väntar. Begäran är en URL från en klient som ber om en resurs, medan svaret är feedback från servern.

Följande är en exempelförfrågan som du kan skicka till LinkedIn API.

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

Och här är ett exempelsvar som det kan returnera:

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

5. Parametrar och rubriker

Du bör också dokumentera dina endpoints parametrar, vilket är alternativ som du kan skicka till dem. Parametrar kan vara ett ID eller nummer som anger mängden eller typen av data som returneras som svar.

Det finns olika typer av parametrar, inklusive parametrar för rubrik, sökväg och frågesträng. Endpoints kan innehålla olika typer av parametrar.

Du kan inkludera vissa parametrar som HTTP-förfrågningshuvuden. Vanligtvis är dessa för autentiseringsändamål som en API-nyckel. Här är ett exempel på en rubrik med API-nycklar:

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

Du inkluderar sökvägsparametrar i ändpunktens brödtext direkt på URL: en. De visar en användare hur och var man ska placera parametrarna och hur svaret kommer att se ut. Orden i hängslen är parametrar.

Du kan också använda kolon eller annan syntax för att representera sökvägsparametrar.

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

Med frågeparametrar måste du placera ett frågetecken (?) före frågan på en slutpunkt. Separera varje parameter efter det med ett et-tecken (&). Microsoft har bra dokumentation om Graph API.

6. Felkoder och felhantering

Ibland misslyckas HTTP-förfrågningar, vilket kan göra en användare förvirrad. Inkludera förväntade felkoder i dokumentationen för att hjälpa användare att förstå felen.

LinkedIn tillhandahåller standard HTTP-felkoder för felhantering:

7. Exempel på kodavsnitt

Kodavsnitt är viktiga delar av din dokumentation. De visar användarna hur man integrerar API: t i olika språk och format. Inkludera hur man installerar och integrerar SDK: er (programvaruutvecklingskit) på olika språk i dokumentationen.

RapidAPI har bra exempel på kodavsnitt för utvecklare:

9. API-versionering och ändringsloggar

API-versionering är en viktig del av API design. Det säkerställer leverans av oavbrutna tjänster till dina användare. Versionering kan förbättra API: t med nya versioner utan att påverka klientapplikationer.

Användare kan fortsätta att använda äldre versioner eller migrera till avancerade i tid. Om det finns nya ändringar i loggarna, inkludera dem i dokumentationen så att användarna är medvetna om det.

Microsoft Graph API har väldokumenterade ändringsloggar:

Slutligen, inkludera viktiga kontakter i dokumentationen för support och feedback. Dessa säkerställer att användare kan nå dig med felrapporter och information om hur man kan förbättra API: et.

Värdet av API-dokumentation

Om du bygger ett API för kommersiellt värde avgör konsumtion dess framgång. Och för att användare ska kunna använda ditt API måste de förstå det.

Dokumentation väcker ett API till liv. Den förklarar komponenterna i detalj på ett enkelt språk som säljer dess värde och användning till användarna. Användare kommer gärna att konsumera ditt API om de har en fantastisk utvecklarupplevelse.

Bra dokumentation hjälper också till att förenkla underhållet och skalningen av API: et. Team som arbetar med API: t kan använda dokumentation för att hantera det.