Först och främst så måste jag ge Sveriges Radio beröm, en klapp på axeln, en stående ovation och en guldmedalj för att de faktiskt har ett öppet API. APIet har varit tillgängligt nu i flera år och har bla använts av SR själva i sina mobilapplikationer och widgets. Detta är mycket mer än de flesta myndigheter och företag i Sverige har gjort och det betyder att SR ligger rätt långt fram redan nu.

Dags för ett bättre public service API

För några månader sedan så kontaktade Jacob Hamacher på SR Digitala Medier mig för att de ville förbättra sitt API. Målet är att använda APIet mer internt och att fler externa utvecklare ska få upp ögonen för det och börja bygga applikationer. Under den senaste tiden så har jag jobbat med SR för att komma fram till vad som ska göras och hur det ska göras. Det har gått riktigt bra och jag tror att de förändringar och förbättringar av APIet som SR planerar kommer att göra en ofantlig skillnad.

I ett antal bloggposter så kommer jag att beskriva projektet. Genom att dela med oss av vad vi har kommit fram till så tror vi att vi kan få bra feedback och att det i sin tur kan göra APIet ännu bättre. Dessutom hoppas jag att detta projekt kan fungera som ett exempel på hur man förbättrar ett existerande API. Lyckas vi så är det ett bra exempel, misslyckas vi så kommer jag att analysera vad som gick fel (rent hypotetiskt alltså, givetvis ska vi lyckas).

Detta behöver göras

Min initiala analys av vad som behöver göras resulterade i en lång lista. Här är huvudpunkterna i prioritetsordning:

1. Bättre kommunikation med utvecklarna. Nu har SR en utvecklingsblogg som täcker all utveckling (webbsajten, APIet etc), men inget annat. För att bygga ett framgångsrikt API så krävs nöjda utvecklare och för det krävs att man faktiskt kommunicerar med dem. Dels så måste´man i god tid informerar om förändringar, dels så måste man skapar en utvecklarcommunity där utvecklare kan hjälpa varandra med sina problem. Att låta mig blogga om projektet är en bra början, öppenhet brukar löna sig.
2. Bättre dokumentation. Dagens dokumentation är en kort lista på de metoder som APIet innehåller och det saknas speciellt en bra översikt på hur alla olika id:n som används relaterar till varandra. Bättre dokumentation bör innehålla en beskrivning av alla dessa id:n och hur de används. Dessutom bör det finnas utförligare beskrivning av varje metod där parametrar beskrivs exempel på anrop och svar visas. Bristfällig dokumentation är en av de vanligaste anledningarna att ett API inte har fler användare, det gör tröskeln att komma igång så mycket högre.
3. Versionshantering. Idag har SR en version av sitt API och de har lagt till funktionalitet till denna version under flera år, detta är en del av förklaringen till varför det ser ut som det gör. För att kunna göra de stora förändringar som krävs så måste det kunna finnas flera versioner av APIet i produktion samtidigt. På så sätt kan stora förändringar införas och applikationer som använder en gammal version kan sakta uppgraderas till den nya versionen.
4. En konsekvent domänmodell. I dagens API så har en typ av data (tex en sändning) flera olika namn, attribut och id:n beroende på vilket backendsystem som används. Detta gör APIet svårt att använda och framförallt svårt att komma igång med. En ny konsekvent domänmodell är ett måste och det kommer att få stort genomslag i hela APIet.
5. Ett konsekvent API. Bättre och konsekvent felhantering, bättre och konsekvent URL-struktur etc. Här finns en hel del förbättringar som kan göras som kommer att göra utvecklare glada (används rätt HTTP statuskod så blir jag personligen glad, jag är inte så svårflörtad).
6. Tydligare användarvillkor. Nu är villkoren: “Materialet som tillhandahålls via API är endast för icke-kommersiellt bruk, och får inte användas på ett sådant sätt att det skulle kunna skada Sveriges Radios trovärdighet.” Exakt vad icke-lommersiellt bruk innebär och vad skada Sveriges radios trovärdighet betyder är omöjligt att veta i förhand. Vem skulle våga satsa ordentligt på att göra en riktigt bra iPhone app för SR om man inte kan ta betalt för det? Skulle det räknas som kommersiellt bruk om iPhone appen var gratis men innehöll annonser? Oklarhet lockar inte duktiga utvecklare och det påverkar hur mycket APIet används.

Har jag missat något? Är min prioritering rätt? Säg vad ni tycker i kommentarerna till detta blogginlägg så hjälper ni till att göra Sveriges Radios API ännu bättre.

Brasklapp: I detta och andra blogginlägg om SRs API så skriver jag om mina åsikter och det är inte nödvändigtvis vad SR tycker och vad SR kommer att genomföra.