Lästid: 9 minuter
API:er får världen att gå runt. Utvecklare använder API:er nästan varje dag – enligt vissa uppskattningar spenderar de hela 10+ timmar i veckan på att arbeta med API:er. Det handlar inte bara om att använda dem, utan också om att forska, googla efter support, studera recensioner och naturligtvis rota runt i dokumentationen. Hur tydligt, enkelt, användbart och stöttat ditt API är avgör hela utvecklarupplevelsen (DX) – en känslomässig reaktion som utvecklarna har på produkten. I API-ekonomin är en bra utvecklarupplevelse grundläggande. API:er som hjälper utvecklare att lyckas och som är roliga att använda kommer att få massor av användare och höja sig över konkurrenterna. Och det börjar i exakt det ögonblick då de öppnar dokumentationen för första gången.
Se den här videon för en introduktion till API-tekniken
I dag ska vi prata om hur man främjar en positiv utvecklarupplevelse i API-dokumentationen. Men först måste vi förstå vad som gör dåliga API-dokumentationer.
Vad utvecklare hatar i API-dokumentation
Den utvecklande gemenskapen är en passionerad gemenskap. Den är särskilt passionerad när det gäller de saker som de inte gillar. Om de inte gillar ett API är det oftast på grund av skräpig dokumentation, även om produkten faktiskt är bra. Här är några vanliga problem som utvecklare har med API-dokumentation.
Den är inte skriven på ett enkelt mänskligt språk. Detta är ett vanligt problem för automatiskt genererade dokument eller dokument som försummas av skaparna. Även om många verktyg för att generera dokumentation gör ett bra jobb med att kommentera koden kan de inte ersätta verkliga förklaringar på engelska som skrivs av en utvecklare eller teknisk skribent.
Den har väldigt få kodprov. Detta är en annan ände av spektrumet där förklaringarna är rikliga, men det finns minimala exempel på den faktiska koden.
Den är endast tillgänglig för registrerade användare. Denna inte så smarta manöver gör ingenting för din marknadsföring. Den frustrerar bara de personer som vill veta vad ditt API gör innan de bestämmer sig för om de vill ha det (vilket varje vettig person skulle göra).
Den är för lång/ej hittas inte/felaktig/inte uppdaterad på flera år osv. Att skapa bra dokumentation är nästan lika viktigt som att bygga ett bra API. Eftersom dåligt skrivna dokumentationer eller sådana som inte kan hittas genom att helt enkelt googla ”Product API” är ett misslyckande för hela utvecklingsarbetet. Om du är intresserad har vi redan redogjort för specifika aspekter av teknisk dokumentation i allmänhet. Men API-dokumentationen förtjänar en särskild artikel. Så hur skriver du bra API-dokumentation?
Anta spec-driven utveckling
Spec-driven utveckling (SDD) liknar testdriven utveckling där du skriver testfall för varje funktion och sedan skriver kod som ska klara dem. Vid SDD skapar du dokumentation eller åtminstone vissa delar av den parallellt med att du bygger ett API, och följer ofta ett visst format för API-beskrivning som kallas specifikation.
En API-specifikation är som en mall för din framtida dokumentation, det enhetliga språk som beskriver utformningen av ditt API, förklarar hur det fungerar och vad man kan förvänta sig av det. Det finns några specifikationer, till exempel RAML (RESTful API Modeling Language), OpenAPI (tidigare Swagger) och API Blueprint, men det finns en trend som går ut på att kombinera alla specifikationer under huven på OpenAPI.
De här specifikationerna har förbyggda dokumentationsverktyg som gör det möjligt att skriva och hantera dina dokument. API Console genererar till exempel automatiskt dokument från RAML- och OpenAPI-format och hjälper dig att köra det i din befintliga webbapplikation eller som en fristående app.
API Console låter dig bygga en webbportal för dina API-dokument från RAML- och OpenAPI-specifikationerna
Källa: Det finns en anledning till att teknisk dokumentation vanligtvis inte skrivs av utvecklare själva – det är tekniska skribenters jobb, experter på att översätta tekniska aspekter till ett läsbart format. Men även tekniska skribenter tenderar att läcka in lite jargong i texten.
En API som alla mjukvaruprodukter skapas för en specifik målgrupp. Men målgruppen för dokumentation är stor. Det finns tre huvudgrupper av dokumentationsanvändare:
- utvecklare som kommer att interagera intimt med dokumentationen
- beslutsfattare som teknikchefer och lösningsarkitekter som snabbt vill avgöra om ditt API kommer att passa bra
- observatörer som journalister, tekniska skribenter och till och med konkurrenter som inte nödvändigtvis kommer att använda ditt API någonsin.
Och även inom var och en av dessa grupper finns det personer med olika färdigheter, roller och behov, och alla bör få en positiv upplevelse av dokumentationen. Hur riktar du dig till dem alla? Genom att rikta in sig på de minst erfarna användarna. Så hur skriver man dokumentationen för en nybörjare?
Start med möjligheterna snarare än teknikaliteterna. Hälsa användarna med en övertygande berättelse om hur ditt API kan berika deras produkt eller göra utvecklarnas liv tio gånger enklare.
Amazon Alexa API-dokumentation börjar med att förklara vad Alexa gör och vilken nytta det kan ge kunden
Visa var man ska börja. API-dokumentationer är ökända för att vara alltför överväldigande och anta att användarna har stor erfarenhet av API:er. Avsnittet om att komma igång är obligatoriskt, och det bör skrivas med tålamod för en potentiell användare.
Facebook ger en tydlig referens för nybörjare och följer processen för att komma igång steg för steg
Skapa instruktioner för de vanligaste användningsfallen. Du vet förmodligen redan vilka funktioner som folk använder ditt API till. Skapa separata avsnitt som tar upp dem och inkludera exempelmeddelanden där.
Använd en konversationston. Utvecklargruppen är avslappnad och informell, så de uppskattar inte torrt företagsspråk även om det låter mer ”professionellt”. Bra dokumentationer talar alltid till människor.
Utbilda om externa verktyg. Om ditt API kräver att du använder och förstår tredjepartsprodukter och koncept som OAuth eller npm, inkludera länkar till dokumentationen eller installationsguider.
Gör det enkelt att lära sig. API-dokumentationen är inte en IKEA-monteringsanvisning, utan en källa för inlärning. Berika din dokumentation med vanliga frågor, handledningar, bloggar och till och med videor när det är möjligt.
Införliva sektioner som är nödvändiga
Under 2019 genomförde SmartBear, utvecklaren av Swagger, en enkätundersökning bland API-utvecklare och -användare. De hittade vilka dokumentationsfunktioner som anses vara de viktigaste i samhället och gav oss en lista över de dokumentationsavsnitt som måste täckas av utvecklare. Vi går igenom några av dem.
SmartBear undersökte 3 000 API-utövare
Exempel. Exempel presenteras vanligtvis som kodstycken, som är tillräckligt användbara men som kan göras ännu mer praktiska. Till exempel genom att inkludera en transkription av fält som det görs i Medium-dokumentationen eller till och med genom att skapa ett mock-API som utvecklare kan testa och använda genom att göra riktiga anrop. Mock API:er kan enkelt delas via en URL eller på GitHub, och om de är gjorda på en viss detaljnivå kan de till och med användas i slutprodukten.
Status och fel. Det finns standardstatuskoder och sådana som är specifika för dina API:er. Det är en bra idé att inkludera alla fel som kan utlösas av ditt API. Fel läggs ofta på en särskild sida i dokumentationen, men det är vettigt att duplicera vissa av dem direkt under slutpunkten där de dyker upp mest.
Autentisering. De flesta API-dokumentationer börjar med autentisering och auktorisering. Den bör innehålla information om hur man får en API-nyckel och hur man autentiserar förfrågningar, inklusive möjliga fel, utgångstider för token och en förklaring om autentiseringskänslighet (i princip en påminnelse om att nycklar inte kan delas och var de kan användas).
HTTP-förfrågningar. Att tillhandahålla webbförfrågningar i HTTP är ett absolut minimum för dokumentation. Det antas vanligtvis att utvecklare vet hur man skickar HTTP-begäranden på sitt eget språk, men ibland inkluderar API-skapare begäranden på olika språk. Detta kan göras automatiskt via verktyg för API-specifikationer och API-hanteringsverktyg som Postman.
Använd industristandardlayout
Om du använder en dokumentationsgenerator är layouten redan bestämd åt dig. De flesta API-dokumentationer ser ut och känns likadana. Om du har använt några sådana vet du hur du ska närma dig nya dokument. Ändå är det en komplicerad uppgift att organisera stora datamängder, göra dem sökbara och lättnavigerade. Här är några egenskaper hos den mest funktionella layouten.
Dynamisk layout. Du kan känna igen ett föråldrat API på dess statiska dokumentation. En enda sida eller till och med ett PDF-dokument räcker inte till år 2020. Dynamiska dokument är lätta att titta igenom, uppdatera och bokmärka.
Stickigt innehåll. Nej, navigeringsfältet distraherar inte och stjäl inte heller värdefullt skärmutrymme. Håll alltid innehållet inom synhåll.
Trekolumnlayout. Den här layouten används inte särskilt ofta, men gör det möjligt att ha ytterligare en kolumn till höger för kodexemplen. Naturligtvis är detta bara meningsfullt om du har massor av text och vill markera kod så att användarna inte behöver bläddra fram och tillbaka eller växla mellan flikar.
HubSpot API-dokumentation använder en layout med tre kolumner
Använd kontrastfärger för syntax. Utvecklare ägnar mycket tid åt att titta på dina kodexempel, så gör dem läsbara och separera olika komponenter med hjälp av färg.
Det här exemplet från Facebooks Graph API-dokumentation visar också hur du kan använda olika flikar för att välja mellan SDK:er
Sparad scrollstatus. Detta är en liten detalj som alla utvecklare kommer att uppskatta. Du kan också använda ankarlänkar för att ange olika delar av sidan om de kopierar URL:n.
Uppmuntra till feedback. Dina dokument är ditt viktigaste marknadsföringsverktyg – om folk älskar dem kommer de att använda ditt API framför konkurrenternas och driva gemenskapen kring det. Det vanliga meddelandet ”Var den här sidan till hjälp?” visar hur väl du svarar på utvecklarnas frågor, och återkopplingsformuläret kommer att användas ofta så länge du levererar.
Överge inte dina dokument
Oföråldrade dokument är det största problemet för API-användare. Det är också ett av de vanligaste misstagen. Utvecklare skriver ofta om uppdateringar flera dagar efter att de rullats ut, och begränsar sig ibland till några få meningar. Detta händer eftersom det inte finns någon etablerad process för dokumentationsuppdateringar och det är ingens ansvar. Här är hur du säkerställer regelbundna och användbara dokumentationsuppdateringar.
Förbered dokumentationen före uppdateringarna. Gör det till ett extra steg i din lanseringsplan, lansera dem inte innan du har välskrivna, detaljerade och redigerade stycken för att introducera dina uppdateringar.
Regelbundet ta bort föråldrade data. Dokumentationen måste ses över ofta, minst en gång varannan månad. Med hjälp av funktioner för användarfeedback kan du upptäcka inkonsekvenser tidigare, och det bör alltid finnas en teammedlem som ansvarar för att granska dem och reagera på uppdateringar.
Använd analyser för att förbättra dokumentationen. Standard API-analyser kommer att berätta vilka slutpunkter som används oftare, så att du kan fokusera på vissa delar av dokumentationen och ge mer användbar information eller skapa dedikerade handledningar. Övervaka de användningsfall som dina API:er används för eftersom det gör att du kan bredda värdeerbjudandet och uppdatera dokumentationen med fler möjligheter.
Goda exempel på API-dokumentation
Det finns massor av bra dokumentationer att utforska och lära sig från. Förutom de exempel som vi har delat med oss av genom hela artikeln finns här några fler som du kan ta del av och notera.
Medium API-dokumentation
Medium API-dokumentation följer inte nödvändigtvis alla regler som vi har listat i dag, men de är utmärkta för den begränsade funktionalitet som det här API:et stödjer – att lägga upp och söka efter publikationer på Medium. De delas på GitHub, har ett verkligt kort men tydligt innehåll med massor av exempel, som alla avslutas med en utskrift av alla parametrar som nämns i koden, inklusive eventuella fel. Det är anmärkningsvärt enkelt, men pålitligt – alla förslag kan lämnas direkt på GitHub och dokumentationen uppdateras regelbundet.
Mailchimp API-dokumentation
Mailchimp inser att den största delen av dess målgrupp är marknadsföringsexperter och använder ett språk som gör det möjligt för även icke-tekniska personer att förstå hur de ska arbeta med deras API:er. Vid en överblick följer varje avsnitt samma struktur:
- vad en slutpunkt gör och vad guiden låter användarna göra
- vad du behöver – eventuella åtkomster eller konton som en användare måste få först
- vad varje funktion är med en textbeskrivning, ett kodexempel på flera språk och ibland skärmdumpar av gränssnittet.
Det finns till och med en kopieringsknapp för varje kodstycke – en detalj som icke-tekniker säkert kommer att uppskatta.
Twilio API-dokumentation
Twilio har som bekant bra API-dokumentation. Även om dokumentationen bara är toppen av isberget av all hjälp som Twilio delar med sig av – det finns SDK:er på flera språk och exempelappar för iOS, Android och webben. Först och främst följer de logiken med tre kolumner med koden direkt till höger om guiden. De enklaste åtgärderna förklaras med detaljer och massor av länkar för ytterligare information och skärmdumpar. Feedback uppmuntras också via en ”Rate this page”-knapp och länkar till supportteamet och taggen på StackOverflow.
Spotify API-dokumentation
Och även om Spotifys webb-API-dokumentation är mycket typisk, har de en hel del ytterligare information i sin plattform Spotify for Developers. Det finns demos för grundläggande funktioner, låtsasappar, live-exempel som byggts med hjälp av Spotify API:er och widgets, wrappers för olika programmeringsspråk och naturligtvis konsolen. Konsolen är i princip en interaktiv dokumentation där du kan fylla i dina (eller exempel på) data och utforska slutpunkter live. Kraftfulla produkter tillsammans med en stark kunskapsbas gör Spotify till en pålitlig partner som utvecklare gillar att arbeta med.
Behandla dokumentationen med omsorg
Dokumentationen är den enda kontaktpunkt som du kommer att ha med de flesta av dina målgrupper, så du måste lära dig att kommunicera klart och tydligt genom den. Det bästa tipset här är att göra det till någons jobb. Ofta handlar det om en teknisk skribent som vet hur man talar till målgrupper med olika färdigheter, som kan översätta utvecklarnas ord till användbara punkter och som övervakar att dokumentationen underhålls och uppdateras i rätt tid. Men att hantera bra dokumentation är möjligt även utan en expert i din personalstyrka. API-hanteringsverktyg som Swagger UI, Spotlight, Apiary och verktyg för specifikation av dokument har en bred funktionalitet som hjälper dig att skapa dokument som utvecklarna kommer att älska.