Det gode API

Det gode API

Vi har igennem de seneste 5 år udviklet 100+ apps til forskellige kunder. 90% af disse apps henter og gemmer data via et API. API’et er på den måde en hel central komponent for både appens udviklingsforløb, kvalitet og afgørende for appens performance.

API’et er bindeled mellem to organisationer og mellem to forskellige IT-systemer og måske også mellem to forskellige IT-teknologier. Derfor er udfordringer relateret til API’et det mest typiske problem i app-projekter.

Der er god økonomi i at lave et godt API fordi det sparer udviklingstid i app-udviklingen, det giver bedre apps og det giver færre fejl.

Vi har samlet 7 tips til hvordan skaber et godt API:

1. Dokumenter API’et og angiv kodeeksempler

Et veldokumenteret API sparer rigtig meget tid for dem der skal programmere systemer op imod API’et og det gør API’et brugbart i andre sammenhænge og for andre projekter. Vi hører ofte at der ikke var tid til at dokumentere API’et. Men sandheden er, at den tid der spares på ikke at dokumentere et API, for længst er brugt hos Android- og iOS-udviklerne, som skal anvende API’et. Samtidig øges API’ets nytteværdi dramatisk på andre projekter, hvis det er godt dokumenteret. Så der er ganske simpelt ingen god undskyldning for ikke at dokumentere et API.

Der er mange gode værktøjer, som gør det lettere at dokumentere et API og levere gode kodeeksempler. Vi bruger selv værktøjet Aglio, som er baseret på standarden API Blueprint. Vi har også gode erfaringer med API’er udviklet med Swagger. Hvis koden er baseret på .NET, så giver værktøjet API Management en ganske glimrende dokumentation.

Hvis man skal vælge – og det vil vi helst ikke – men så vil vi hellere have kodeeksempler end dokumentation.

2. Test API’et – gerne med et automatiseret tool

Ligesom alle andre IT-produkter skal API’er testes. Det siger sig selv. Men i modsætning til f.eks. en app eller en hjemmeside, så er det kun programmører der reelt kan teste et API. Det giver ofte det problem, at projektlederen eller kunden af et API ikke kan teste slutresultatet. Det betyder igen, at testen ofte overlades til den udvikler der har lavet API’et – og det er dumt.

Prioriter testen og lad altid en anden udvikler – gerne en arkitekt – teste API’et.

Der findes flere gode værktøjer til at automatisere tests af API’er. Vi er selv glade for web tool’et, RunScope. RunScope opsætter et testforløb lidt ligesom en serie Unit Tests, og så kan projektlederen bare gå ind på hjemmesiden og trykke på “Run” for at teste API’et. Det sparer rigtigt meget tid.

3. Vær konsistent med logik og navngivning

Når man bruger et API tilgår man et IT-system udefra og har kun og skal kun have begrænset viden om de bagvedliggende processer og logikker. En af de udfordringer vi ofte møder er, at navngivning og logikken på tværs af de forskellige kald varierer. Det er stærkt forvirrende og kan være årsag til fejl og misforståelser. Sørg derfor altid for at API’et er konsistent i sin logik og navngivning.

Vi hører ofte den forklaring, at det bagvedliggende system har udviklet sig over tid, og derfor er API’et inkonsistent i sin navngivning og logik fordi det er lavet hen af vejen og afspejler underliggende funktioner. Set udefra er det bare en dårlig undskyldning og noget der gør API’et svært at arbejde med.

En anden fejl vi desværre også ofte ser er, at dansk og engelsk blandes i API’ets navngivning og dokumentation. Noget af det grimmeste kode man kan få er danske feltnavne. Undlad altid danske feltnavne o.s.v.

4. REST / JSON

Der findes mange forskellige teknologier, standarder og fremgangsmåder for at lave API’er. Skal der udvikles Android og iOS apps, så er det bedste teknologi-valg et REST-baseret API hvor data overføres via JSON-formatet. Det giver både den mindste udviklingstid og den bedste performance.

Hvis der skal overføres store datamængder kan selv JSON blive lidt tungt at arbejde med. I sådanne tilfælde bør man overveje at benytte et standardiseret, binært format i tillæg til JSON som f.eks. Protocol BuffersMessagePackCBOR eller Flatbuffers. At understøtte et ekstra dataformat er typisk en relativ lille investering i forhold til den samlede investering i forbindelse med udviklingen af et data API.

XML var fantastisk da det kom frem i slutningen af 90’erne især pga. den overskuelige dokumentation og ideen om at både mennesker og maskiner skulle kunne læse formatet. Men set i en app-sammenhæng, hvor performance og størrelsen af dokumenter betyder en meget, så er JSON-formatet langt at foretrække frem for XML.

5. Hav styr på brugsscenariet – API’er er mange ting

En udfordring med API’er er, at man principielt ikke kan vide hvilke eksterne systemer der skal hente og sende data til det bagvedliggende system og derfor kan det være svært designe API’et rigtigt.

Nogle af de “patterns” for API’er vi ofte møder er:

  • Transaktions-API: Et transaktions-API er designet, så det eksterne system let kan gennemføre transaktioner. Hvis vi f.eks. har et API til et økonomisystem, så vil transaktions-API’et give mulighed for at gennemføre transaktioner såsom “Opret faktura-linje”, “Opret faktura” etc. For et transaktions-API er de enkelte processer nedbrudt til de mindste logiske enheder, og der er indbygget logik for hvordan transaktionen modtages og håndteres, og der er taget forbehold for alle de forskellige fejl der kan opstå i transaktionerne.
  • Rapporterings-API:  Et rapporterings-API er et API, hvor det eksterne system typisk skal vise rapporter eller aggregerede data fra det bagvedliggende system. For et økonomisystem kunne det f.eks. være at vise den samlede omsætning for et forretningsområde i indeværende måned. Her er det langt mere effektivt at placere den forretningslogik der skal generere rapporten på serveren, og så kun sende det samlede resultat.
  • Delta-API: Et Delta-API sender data der er oprettet, modificeret eller slettet siden sidste gang klienten har hentet data. Det er f.eks. nyttigt hvis du har en liste over nyheder – så kan brugerens app nøjes med at hente de nyheder der er opdateret siden sidste gang brugeren hentede data. Fordelen ved et Delta-API er, at det kan give bedre performance i f.eks. en app og at det mindsker loaden på serveren.

Det man skal tænke over når man designer sit API er, om man kan flytte forretnings-logikken til serveren og hvordan man kan give den bedste performance til brugeren.

6. Undgå platformsspecifikke løsninger

Gennem tiden har flere af de store IT-prdoucenter (Microsoft, Sun, Apple o.s.v.) forsøgt at lave deres egne standarder til at udveksle data. I forhold til API’er er det i Danmark især Microsofts WCF-teknologi og Microsofts forskellige produkters brug af SOAP, som vi løber ind i. Udviklingstiden og performance på iOS og Android apps er bedre på et REST/JSON-API end på et SOAP/XML-baseret API. Derfor foretrækker vi JSON.

Microsoft promoverede i nogle år teknologien WCF (Windows Communication Foundation), som via en service-baseret tilgang er en yderligere indpakning af SOAP/XML-API’er. Problemet som app-udvikler er, at der ikke findes gode værktøjer på hverken iOS eller Android til at “konsumere” WCF-API’er, og derfor skal man mere eller mindre per håndkraft udpakke dataene. Dette bliver ikke bedre af, at navngivningen ofte bliver automatisk tilrettet og svær at læse af WCF-standarden. Så, igen, vil det øge udviklingstiden i app-udviklingen.

7. Giv nu lidt kærlighed til projektet

Vi elsker API’er. API’er er det der gør at data kan genbruges, sættes sammen på nye måder, skabe ny værdi og nye services. Virksomheder som Google, Facebook, Twitter og Amazon har skabt formuer og revolutioneret vores verden ved at se mulighederne i det gode API. Så, vi ville ønske at den samme kærlighed blev lagt i API-design og -udvikling i langt flere virksomheder.

Skriv en kommentar

 
Af Jakob Mikkelsen
jakob@greenerpastures.dk
+45 70 26 00 69