Skip to main content

Bild

Image

woman_phone
Blogg

Utvecklarportaler – dokumentationen är död, länge leve dokumentationen!

Sektioner

Image

Stefan Påsse

Text

Jag har jobbat med integration i ett par decennier, och arbetat med många olika typer av organisationer, branscher och företag. 

Jag kan utan tvekan säga att den tid som spenderats utan ordentlig planering och struktur är det arbete som läggs ned på att kommunicera hur man använder respektive integration. Närmare bestämt den något endimensionella arbetsuppgiften att läsa och skriva teknisk dokumentation. Som regel snarare än undantag räckte det dessutom inte med den producerade dokumentationen, utan ytterligare stöd i form av mail, telefonkontakt eller faktiska möten behövdes för att förmedla informationen. Allt som allt en rätt frustrerande uppgift, och en avgörande faktor som gör att onboarding av en ny användare till en integration inte skalar upp särskilt effektivt. I korthet, en dålig utvecklarupplevelse.

Med en modern API som kopplingspunkt för fler och fler integrationsscenarios, visar sig utvecklarportaler kunna dämpa frustrationen. Det gör det väsentligt enklare och smidigare att introducera nya användare i en digital tillvaro som kräver kortare ledtider, och flexibla arbetssätt.

Om vi antar att vi tycker att flexibla arbetssätt och glada utvecklare är bra, låt oss titta lite djupare på de förutsättningar och funktioner en utvecklarportal ger:

  • Marknadsföring
  • Sökfunktion
  • Instruktioner – bruksanvisning
  • Abbonemang
  • Analysverktyg
  • Support

Marknadsföring – att visa att en API existerar  

Första steget till att använda en API är att känna till att den finns – därför behövs en enkel katalogfunktion med beskrivningar som förklarar användning och nytta av respektive API på ett 
centralt ställe. I de flesta fall bör det här ligga på portalens startsida.

 

Sökfunktion – att beskriva nyttan och användningsområdet för en API

Referensdokumentationen för en API beskriver respektive slutpunkt. Man bör exemplifiera hur API:n används för ett urval av klienttyper med kodsnippets för de vanligaste språken. Det här gör dokumentationen enklare att ta till sig oberoende av vilken tidigare erfarenhetsnivå man kommer ifrån. En interaktiv API konsol ger utvecklaren möjlighet att anropa och testa API:n utan att koda ett testcase separat. För en utvecklare är det här väsentligt enklare att ta till sig än en textbaserad dokumentation.

 

Instruktioner – bruksanvisning för att nyttja API:n från sin applikation

Uppstartsdokumentation med steg-för-steg instruktioner. Troligtvis en detaljerad beskrivning av hur man nyttjar API:n (autentisering & auktorisering). Ett flertal kodexempel är alltid uppskattat.
 

Abbonemang

Utvecklaren skall kunna begära access till API:n genom portalen för sin applikation. Man skall kunna se status på sin förfrågan och alla aktiva abbonemang.

 

Analysverktyg

Portalen bör kunna visa åtminstone grundläggande analysdata för respektive abbonemang som visar nyttjandevolymer, responstider, svarskoder etc.

 

Support

En supportdel i portalen med åtminstone FAQs bör finnas. En aktiv kanal för supportärenden och kanske ett community med Q&A forum.

Förhoppningsvis har den här bloggposten inspirerat er till att överväga en Utvecklarportal eller bygga vidare på er befintliga lösning för att hjälpa och stötta era utvecklare till en gladare och mindre frustrerande tillvaro!

Hör gärna av er till mig om ni vill ha mer tips och hjälp för att skapa en fantastisk utvecklarupplevelse.

Stefan Påsse
Integration på Enfo  
stefan.passe@enfo.se 
Linkedin

Dela