Så skapar du ett eget api

Det är svårt att hitta en större webbaktör i dag som inte erbjuder ett webbaserat api. Till och med myndigheter har hoppat på tåget och möjliggjort många smarta tjänster som använder deras data. Kollektivtrafik och väderinstitut var bland de första, men på senare tid har även kommuner och vårdsektorn börjat öppna sina data.

Den svenska api-samlingen apikatalogen.se listar närmare 300 öppna api:er, och den internationella sajten programmableweb.com samlar över 11 000.

Gör rätt från början

Men för att ett api ska komma till användning måste det vara genomtänkt. Framförallt måste det bli rätt från början, eftersom det är oerhört mödosamt att genomföra ändringar när gränssnittet väl gjorts officiellt.

Tyvärr faller ofta hela ansvaret för framtagning av ett api på utvecklare. Men alla delar av verksamheten bör involveras, då det är lika mycket en fråga om affärsnytta och design som det är ren teknik. Även tilltänkta användare av api:et utanför verksamheten bör involveras för att få fler perspektiv. Ett slarvigt byggt api är inte bara bortslösade resurser och tid, det kan även ge ökade kostnader i form av krävande support.

I den här artikeln ska vi visa steg-för-steg hur processen kan se ut när ett api tas fram. Exempelfallet är den klassiska att göra-lista-tjänsten.

Innan ett api tas fram måste givetvis datamodellen vara stabil. Att påbörja arbetet med ett api parallellt som tjänsten i sig utvecklas från grunden är sällan en bra idé eftersom datastrukturen ofta förändras under det arbetets gång.

När det gäller utformningen av api:et finns ett antal rekommenderade riktlinjer. Det ska givetvis vara lätt att både lära sig och använda, även utan dokumentation.

Om api:et inte kräver någon autentisering bör det vara möjligt att utforska med en simpel webbläsare.

Dess utformning bör vara anpassad för användarna. Vilken terminologi bör användas för att göra det så lättförståeligt som möjligt? I vårt scenario skulle vi i api:ets anrop kunna använda namn som taskObject och userObject, då det tycks naturligt för oss. Men för en utomstående användare är förmodligen todo och person lättare att förstå.

För att api:et ska utformas på bästa sätt och väl exponera de data som efterfrågas bör tilltänkta användare av api:et involveras. Man bör alltså tidigt klargöra vem som ska använda api:et och hur det ska användas.

En annan viktig fråga är vilka data som av olika skäl inte bör offentliggöras. För den som verkar i en konkurrensutsatt bransch kan vissa data vara tryggast att behålla inom de egna systemen. Ofta är en generell lösning en enklare utgångspunkt än en mer specifik lösning. En minimal grund är också enklare att förändra och bygga på. Dessutom kommer de tilltänkta användarna att ha lättare att förstå och komma med synpunkter om specifikation hålls kortfattad.

I vårt scenario börjar vi med att endast tillgängliggöra konton samt dess personer och uppgifter. I applikationen kanske uppgifter även har taggar och samtliga data är sökbara, men det kan vi alltid lägga till i framtiden. Det finns förmodligen också en mängd data som används bakom kulisserna, till exempel användares beteende i applikationen, men sådana finns det naturligtvis ingen anledning att visa upp.