Rigtig mange af de apps vi udvikler bygger på en variation af følgende tekniske arkitektur:
- En eksisterende server-komponent har værdifulde data
- For at kunne eksponere data fra server-komponenten, udvikles der et API
- App’en henter data via API’et og viser disse på mobiltelefonen – gerne på en ny og frisk måde
- Ofte kombineres data fra server-komponenten med andre data eller andre services, så der skabes en helt ny service tilpasset en mobil kontekst
I mange af disse projekter skal API’et udvikles eller der eksisterer allerede et halvfærdigt API, som skal justeres og gøres klart.
Udviklingen eller opdateringen af API’et gøres alt for ofte til et rent teknisk spørgsmål – skal API’et laves som REST eller SOAP? Skal det anvende JSON eller XML? Disse spørgsmål er bestemt relevante og vigtige.
Men, de vigtige spørgsmål om hvilke forretningsmuligheder API’et kan åbne op for, hvordan laves API’et på en måde så det reelt kan genbruges stilles ofte ikke.
Min erfaring er, at der spildes mange penge og mange muligheder, fordi der laves dårlige, ikke-gennemtænkte og ikke-dokumenterede API’er. Fordi det er svært for ikke-teknikere at tjekke et API og svært at forstå det, så overlades API’et fuldstændigt til teknikere. Og fordi det mærkeligt nok tit er lav-status at udvikle API’er, så er det ofte ”den nye mand” eller junior-udviklere der laver API-opgaverne. Resultatet er dårlig kvalitet, manglende forretningsforståelse og spild af forretningsmuligheder.
Det lyder måske banalt – men min erfaring er, at API’et både nedprioriteres og at dets reelle værdi ikke forståes. Der er selvfølgelig undtagelser – men vi ser fere dårlige API’er end gode.
Var jeg projektleder eller forretningsudvikler i en større organisation ville jeg sikre mig, at følgende spørgsmål blev stillet inden man satte en udvikler i gang med at kode og dokumentere:
- Skal der udvikles et API der senere kan genbruges?
- Hvordan skal API’et dokumenteres, så det reelt kan anvendes af 3. part?
- Vil det være en fordel at gøre API’et åbent eller lukket?
- Hvilke services eller data er relevante? Kan vi forudsige kommende services?
- Et API er en ”kontrakt” mellem forskellige IT-systemer – hvordan sikrer vi at vi overholder denne ”kontrakt”?
- Hvordan tjekker man som ikke-tekniker et API?
Lad os tage spørgsmålene et ad gangen:
1. Skal der udvikles et API der kan genbruges senere?
Et APIs funktion er at eksponere data eller services, så andre IT-systemer kan anvende disse data eller services på en enkel og sikker måde uden at skulle kende til de bagvedliggende systemer.
Lad os sige vi har en virksomhed der driver togdrift og vi er ved at lave et API, der kan eksponere data om køreplaner og forsinkelser. Vil det senere være relevant at eksponere disse data i andre IT-systemer? Vil vi måske skulle lave notifikations-services, vise køreplaner på elektroniske tavler eller på anden vis offentliggøre disse? Svaret på disse spørgsmål er uomtvisteligt ja. Derfor skal der selvfølgelig udvikles et API der kan genbruges senere.
Skal API’et kunne genbruges til andre projekter, skal det selvfølgelig dokumenteres og det skal kodes på en måde, så det kan anvendes uden at man har viden om interne systemer og terminologier etc.
Det er klart at det øger udviklingsomkostninger en smule at lave et generelt API. Men, det er minimalt i forhold til hvad der alligevel skulle investeres.
2. Hvordan dokumenterer vi et API, så det reelt kan anvendes af 3. part?
I 4 ud af 5 API’er vi har arbejdet med det sidste år, har den eneste dokumentation været en url og måske et kodeeksempel. Så, en god start er lave noget dokumentation. Næste udfordring er, at dokumentationen skal være skrevet til eksterne programmører. Ofte er navngivning og forklaringer indadvendt – forstået på den måde at API’et fortsætter med at bruge serversystemet termininologi og kontekst. Dette giver bare sjældent mening set udefra.
Et andet problem vi nogle gange møder er, at dokumentationen er et 400 siders langt dokument. Hvis man siddder med et lille 80 timers projekt – så kan det virke en smule overvældende.
Den dokumentation vi foretrækker er når dokumentationen er lavet som et lille website med små kodeeksempler og forklaringer. Vi har lavet en lille opave baseret på data fra Google Analytics Reporting Engine – og deres dokumentation er forbilledlig: https://developers.google.com/analytics/devguides/reporting/core/v3/
De typiske problemer ved implementeringen og dokumentationen af API’er er:
- Der er ingen dokumentation eller forældet dokumentation
- Navngivningen er dårlig
- Navngivningen er baseret på det interne systems (legacy)-terminologi
- Forskellige services og feeds i det samme API bruger forskellige navne for de samme data
- Der anvendes dansk navngivning
3. Vil det være en fordel at gøre API’et åbent eller lukket for vores virksomhed?
Tager vi igen eksemplet med jernbaneselskabet – så er det oplagte svar ”ja”. Det er i selskabets interesse, at der er så mange services som muligt der integrere data om togafgange – så disse f.eks. vises sammen med tidsplaner for andre trafikformer, så de advarer kunderne om forsinkelser etc.
I nogle tilfælde er svaret selvfølgelig ”Nej”, hvis virksomheden igen lever af at sælge disse data. Men, igen kan det være en fordel at indbygge en generisk sikkerheds-model, så virksomheden kan begynde at sælge data via API’et til partnere.
Vores erfaring er, at langt de fleste virksomheder og organisationer har en interesse i at deres data bliver brugt og integreret i andre systemer. Derfor skal API’et være åbent.en det reelle værdi ikke forståes.’ styr på. Men, nu har jeg bare set fejlen en hel har finansieret. et godt API, så se lige DS
4. Hvilke services eller data er relevante? Kan vi realistisk forudsige kommende services?
Den er faktisk sværere. I eksemplet med togdriften er det ret oplagt – men det er ofte svært at forudsige hvilke data der er relevante i kommende projekter eller IT-systemer. Hvis det er svært vil det ofte være klogt at lade være med at forsøge, og kun eksponere præcist de data der skal bruges her og nu.
Men, det er helt sikkert, at det kræver reel domæneviden og forretningsforståelse for at kunne afgøre hvilke data og services der skal gøres tilgængelige. Så, hvis man sætter den senest ansatte programmør til at udvikle API’et – så kan vedkommende helt sikkert ikke afgøre hvad der formentligt bliver relevant.
5. Et API er en ”kontrakt” mellem forskellige IT-systemer – hvordan sikrer vi at vi overholder denne ”kontrakt”?
En anden typisk problemstilling er, at der er udviklet en app som trækker på data fra et API som en intern IT-afdeling har bygget. Et år senere holder app’en eller servicen op med at virke – fordi API’et er slukket, blevet ændret eller er flyttet til et nyt domæne. Med andre ord blev den ”kontrakt” som API’et er, ikke overholdt.
Det vigtigste er, at sikre sig hvem der har ansvaret for API’et. Hvem ved hvilke systemer der trækker på data fra API’et og hvem er ansvarlig for at API’et kører? På den måde er et API fuldstændigt ligesom et website eller en ydelse – der er nogen der skal ”eje” det”. Har virksomheden et overvågningssystem til sine websites er det oplagt at koble API’et på dette system, så det overvåges.
Dernæst skal der laves en plan for hvordan API’et opdateres og udvides. Den typiske løsning er, at man versionerer API’et, så man ved at f.eks. version 1.0 fortsætter med at fungere efter at version 1.1 er releaset.
6. Hvordan tjekker man som ikke-tekniker et API?
Som ikke-tekniker kan et API godt være svært at gennemskue. Men, i praksis er det faktisk ofte ret simpelt hvad det er der foregår. De fleste API’er vi arbejder med er åbne – og følger en helt simpel struktur:
- App’en kalder API’et og efterspørger data
- API’et sender data tilbage på struktureret form – typisk som XML eller JSON
Nogle gange laves der først et login, hvor API’et sender en ”Nøgle” tilbage. Og denne ”nøgle” bruges så ved alle kald.
I et enkelt REST API kan man kalde API’et direkt via et link. Prøv f.eks. at åbne følgende link i en browser: https://raw.github.com/currencybot/open-exchange-rates/master/latest.json.
Dette API returnerer en liste over valutakurser i forhold til US$ i JSON-formatet og kunne f.eks. bruges til at lave en simpel valutaomregner.
Prøv så at åbn websiden http://jsonformatter.curiousconcept.com/ og læg https://raw.github.com/currencybot/open-exchange-rates/master/latest.json ind i feltet “JSON data url” og klik på “Proces”. Nu formatteres JSON’en pænt – og det er tydeligt hvad der foregår.
Hvis det var din IT-afdeling der havde eksponerer centrale data for jeres virksomhed, vil du kunne tilgå data sådan.
Andre typer af API’er er “pakket ind”, så det er nemmere at arbejde med disse i udviklingsprocessen. Men, der er altid værktøjer, som kan åbne API’er – tjek med udviklingsafdelingen hvordan man kan gøre dette.
Morale – DSB har fattet det
Og for lige at komme med et eksempel på en organisation der virkelig har fået fuld valuta for at lave et godt API, så se lige DSBs fine DSB Labs: http://dsblabs.dk/webservices – og nyd hvor mange apps og services der trækker på API’et – http://dsblabs.dk/category/show/1281442209 – vel at mærke både apps og services som DSB har finansieret og apps og services som andre har finansieret.