I mitt arbete med att hitta APIer för svenska API katalogen så har jag sett ett par hundra svenska APIer. Det som väldigt många av dem har gemensamt är bristen på publik API-dokumentation. Ofta måste man kontakta en säljare för mer information eller redan vara kund för att ens få se dokumentationen. Om målet är att få utvecklare att använda APIet så är bristen på dokumentation en gigantisk nackdel och näst intill en garanti att kreativa utvecklare ser sig om efter mer lättillgänglig alternativ.

Personligen kan jag inte komma på någon giltig ursäkt att dölja sin API-dokumentation, däremot kan jag komma på några dåliga ursäkter. Låt mig gå igenom de dåliga ursäkterna en i taget…

Ursäkt 1: “Vårt API är inte till för allmänt bruk”

OK, ert API är endast för era betalande kunder och ingen annan, vad har det med API-dokumentationen att göra? Bara för att dokumentationen är publicerad på er sajt så betyder det inte automatiskt att alla har rätt att använda ert API, det kan ni lätt kontrollera via API-nycklar eller OAuth bara för att nämna några möjligheter. Det är absolut inget fel i att begränsa tillgängligheten till ert API (även om en begränsad gratisvariant är bästa vägen att rekrytera utvecklare, men det är ett helt annat blogginlägg), eller att ta betalt för era tjänster, men det har inget med dokumentationen att göra.

Genom att ha bra API-dokumentation så gör ni det tydligt och klart för betalande och potentiella kunder, existerande och potentiella partners samt utomstående utvecklare vad ert API faktiskt kan göra. Om ert API tillför värde så är det tydligt och klart för alla och se och det gör hela ert system mycket mer attraktivt. Publik API-dokumentation är alltså en del av marknadsföringen!

Ursäkt 2: “Vår API-dokumentation är inte så bra”

Är er API-dokumentation så dålig att ni inte vill visa upp den för allmänheten så vill ni väl absolut inte visa upp den för betalande kunder! Om något så har väl betalande kunder rätt att förvänta sig ännu utförligare dokumentation än någon annan. Använder ni den här ursäkten så finns det bara två vägar framåt – fixa till er API-dokumentation eller håll APIet helt internt och låt ingen utomstående, inte ens era kunder, använda det.

Ursäkt 3: “Vi har ingen API-dokumentation”

Har ni ingen som helst API-dokumentation så ska ni inte heller låta någon använda ert API. Vill ni använda APIet internt och hoppas att dokumentation inte behövs så är det ert eget problem, men utsätt inte kunder eller någon annan för det.

Sluta komma med ursäkter

Vill ni att ert API ska vara framgångsrikt eller vill ni ha ytterligare en marknadsföringskanal för era tjänster så sluta komma med ursäkter och publicera bra API-dokumentation. Har ni inte bra API-dokumentation idag så publicera det ni har med brasklappen att dokumentationen är i beta (eller “preview” som innetermen är idag), men sitt och håll på den.

Behöver ni hjälp med API dokumentation eller något annat API relaterat så hjälper vi på Dopter gärna till. Ta också en titt på vår API konsol på APIHQ, ett verktyg för att skapa interaktiv API-dokumentation som gör det enkelt att komma igång med ett API utan att skriva en rad kod.