321 Julekalender 2022
Snart nytt år, og dermed ny intern julekalender i 321. Vi har stort sett alltid godt med aktivitet på vår fag-kanal på Slack. Det kan være at noen deler en artikkel de har lest, anbefaler en bok, eller at noen løfter frem et problem eller utfordring de har møtt ute i oppdrag.
I jula pleier vi, som mange andre IT-selskaper, å "steppe opp" enda et hakk her for å sørge for faglig påfyll gjennom hele førjulstiden. Alle 321-ere, det være utviklere eller designere, skriver 2 poster der de forteller om noe de ønsker å presentere for de andre. Vi prøver å oppfordre til kortfattede innlegg, det er tross alt mye annet som skjer rundt juletider både i oppdrag og privat. Men det er alltid noen som har problemer med å holde igjen. Eirik sine "wall of text" ble vi kjent med allerede i fjor, i år med sterk konkurranse fra Martin.
Vi ønsker også å dele noe av dette med de som ikke er heldige nok til å være med på fagkanalen vår, så her kommer et utdrag fra årets julekalender.
Luke 13: OpenAPI
OpenAPI spesifikasjonen er en spesifikasjon for å beskrive HTTP API på en språkagnostisk måte (programmeringsspråk altså). Spesifikasjonen het opprinnelig Swagger Specification, en spesifikasjon som ble utarbeidet av Smartbear. Etter hvert som den fikk mer fotfeste, så ble det bestemt at selve spesifikasjonen skulle doneres til en leverandøruavhengig organisasjon, og OpenAPI Initiative ble etablert. Swagger 2.0 og OpenAPI 2.0 er derfor den samme spesifikasjonen, men etter hvert har OpenAPI blitt utviklet videre, og er nå på versjon 3.1.
Andre spesifikasjoner som finnes der ute er RAML og API Blueprint.
I den siste tiden har det blitt mer populært å jobbe API First eller API Design First, i motsetning til Code First. På denne måten jobber en frem spesifikasjonen for seg selv. Ut ifra spesifikasjonen kan en generere klient- og server-kode slik at en er sikker på at spesifikasjonen (som også vil utgjøre dokumentasjonen) og implementasjonen alltid er i synk. Vi sier at spesifikasjonen er en "first class citizen", dvs en fullverdig komponent, og ikke bare et biprodukt (av code-first). En kan også enkelt sette opp en mock-server som baserer seg på spesifikasjonen, noe som gjør at en kan begynne å kode klienter før selve serveren er implementert. Her vil en få kjappere feedback og kortere iterasjoner for å komme frem til et godt grensesnitt mellom server og klient.
Her har jeg lagd et repo som viser en veldig enkel spesifikasjon, samt noe kode som automatisk genrerer klient- og server-kode i java-format (vha maven): https://github.com/mortenberg80/openapi-example
Generatoren støtter mange forskjellige språk og bibliotek.