Hvorfor er god API dokumentasjon så vanskelig?

[Tuva]

Hei!
Jeg jobber med å enkelt dokumentere og tilgjengeliggjøre APIer på tadata.no. Vi opplever at veldig få klarer å dokumentere APIene sine på en måte som gjør at de er enkle å forstå og ta i bruk. Er det flere her som opplever det samme? Og hva kan man gjøre for at APIer skal bli mer tilgjengelige?

[espen.slotvik]

Hei Tuva
Veldig bra at dere jobber med å skape gode oversikter over APIer som finnes der ut. Vi gjør det samme i data.norge.no og opplever også at det kan være utfordrende å få dataeiere til å publisere sine APIer og dokumentasjon av dem. Vårt utgangspunkt har vært felles behov som virksomhetene i forvaltningen har løftet frem knyttet til tilrettelegging for mer datadeling. Da er god dokumentering av APIer viktig, men det er også behov for god forståelse av de dataene man får via APIene. Derfor er det også mulig å koble APIene mot datasettbeskrivelser med sine informasjonsmodeller og begreper. Det siste som nå er under utvikling er tjenestekatalog. Alt dette for å ivareta de semantisk, organisatoriske og juridiske detaljene i data som deles i tillegg til det rent tekniske.
Opplever dere at disse dokumentasjonsbehovene også etterspørres av brukere av APIene dere publiserer på tadata.no, eller er dette særbehov først og fremst knyttet til gjenbruk i offentlig sektor?

[Tuva]

Hei Espen,
Ja, vi erfarer også at API tilbydere sliter med å dokumentere på en måte som gjør at brukeren både forstår hvilken data de får tilgang til og hvordan man rent teknisk skal implementere. Vi ser mange eksempler på at tilbydere prøver å gjøre begge deler i samme dokumentasjon, hvilket ofte fører til at hverken dataen(produktet) eller implementasjonen blir enkel å forstå. Jeg opplever nok ikke at våre brukere stiller like høye krav til dokumentasjon som det du beskriver over. Det er selvsagt behov for å forstå hvor dataen kommer fra, hva betingelsene for å bruke den er og hvordan man kan implementere mot den, men vi opplever at skoen trykker mest på det å enkelt kunne få en oversikt og forstå hva man får tilgang på, også for en person som ikke nødvendig vis er utvikler.

I Tadata fokuserer vi på at det skal bli enkelt for brukere å sette seg inn i hvilken data som ligger bak et gitt API og hva som skal til for å få tilgang til den. Vi har laget en testfunksjon som gjør at brukere kan kjøre spørringer direkte i nettleser med input fra enkelt forståelige felter, og opplever at dette blir mye brukt og er av stor verdi. En litt enklere og mer praktisk tilnærming til dokumentasjon kan man vel kanskje si. Kanskje er dette noe man kan benytte seg av på toppen av mer omstendelig dokumentasjon i det offentlige også?