API – det handler om forretning

Når man deltager i udviklingen af et it-system, støder man uundgåeligt på API’er.

Et API (Application Programming Interface) beskriver den funktionalitet, et system stiller til rådighed for andre systemer – på samme måde som et UI (User Interface) er den funktionalitet, der stilles til rådighed for de mennesker, der bruger systemet.

Et API har selvfølgelig en konkret implementering, men det vigtigste er faktisk den forretningsmæssige beskrivelse: Hvad kan systemet?

Når man selv skal producere et API, er der fundamentalt to måder at angribe opgaven på: Man kan vælge at kigge indefra og ud – eller man kan vælge at anskue sit system udefra.

Indefra og ud eller udefra og ind?

Lade os tage et eksempel: Styrelsen for Dataforsyning og Effektivisering stiller et API (DAWA) til rådighed, der gør det muligt at finde et hav af oplysninger om adresser i Danmark.

Da de i sagens natur ikke aner, hvad anvendere af systemet har brug for, gør de det muligt at søge på kryds og tværs. De kigger med andre ord indefra og ud.

Omvendt har klubben, hvor fodboldtræner Jürgen huserer, et lidt mærkværdigt adressesystem, hvor den tidligere formand, i kraft af sit mangeårige virke som landmåler, har valgt at registrere spilleradresser med geokoordinater.

Det har systemet til kontingentopkrævning det lidt stramt med, så der er behov for at udvikle en service, der kan konvertere et sæt geokoordinater til en adresse.

Med andre ord er der et forretningsmæssigt behov for et API, der kan opfylde dette specifikke behov – vi kigger altså udefra og ind.

Men kunne systemet ikke bare bruge DAWA?

I princippet, jo. Men det kræver lidt ekstra arbejde for dem, der skal benytte API’et:

DAWA gør det nemlig kun muligt at fremsøge adresser inden for et polygon – det er lidt besværligt, og desuden får man (potentielt) flere resultater.

Derfor kan vi med fordel lave et API, der benytter DAWA, men fra et kalder-perspektiv er mere simpelt.

Selve implementeringen vil nok se, hvilken af de returnerede adresser, der er tættest på det søgte – og man kunne forestille sig en intern metode, der tilføjer afstand til de søgte koordinater for hver funden adresse (her kan Pythagoras anvendes som en rimelig approksimation, selv om vi arbejder på kugle…).

Husk de forretningsmæssige behov

Skal man så ikke udstille denne interne metode også? Det kunne jo tænkes, at andre kunne have glæde af den.

Her skal man undgå at lade sig rive med af begejstringen. Hvad nu hvis DAWA på et tidspunkt dør, og vi skal bruge en anden leverandør?

På det tidspunkt vil det være ærgerligt, at erstatningen skal understøtte muligheden for at fremsøge flere resultater – det var jo slet ikke et forretningsmæssigt behov.

Når vi kigger udefra og ind, skal vi altså huske på, hvad der er forretningsmæssigt behov for.

Det skal udstilles så fokuseret som muligt – og så simpelt at anvende som muligt.

Det sidste er en selvstændig pointe: Lad være med at forvente, at kaldere af dit API har en viden om implementering eller bagvedliggende datamodel. Forlang kun parametre, som er forretningsmæssigt meningsfulde, og returmér kun data, der er relevant.

I det konkrete tilfælde skal du forlange længde- og breddegrad og returnere en postadresse. Hverken mere eller mindre.