item

Swagger 2.0 og Domino data, er det mulig?

Publisert: 20. april 2016 | Ketil Hjerpaasen

Jeg ble utfordret av en kunde her i vinter. De ønsket å vise dominodata i en ny applikasjon. Kunne dataene hentes ved hjelp av REST? Han ville gjerne ha disse tjenestene dokumentert. Derfor undret han på om det var mulig å benytte Swagger til å dokumentere REST tjenester på domino. En flott utfordring :-)

Hva er Swagger?

Veldig enkelt fortalt er Swagger et API som er tilgjengelig på mange plattformer og forenkler prosessen med å implementere, dokumentere, validere, teste og bruke REST tjenester.

Målet er å definere en standard som, uavhengig av progsrammeringsspråk, lager et interface til REST apier, som gir både mennesker og maskiner (pc) mulighet til å oppdage og forstå tjenesten uten tilgang til kildekode, dokumentasjon eller gjennom nettverkskommunikasjon.

(kilde: fritt oversatt fra http://swagger.io)

Hva er REST?

Representational state transfer (REST) er en måte å utveksle data på.

Jeg har ikke tenkt å fortelle hva REST er her. Det finnes det mye god informasjon om, feks. på wikipedia :https://en.wikipedia.org/wiki/Representational_state_transfer

Utfordringen

Først trodde jeg dette kunne bli vanskelig og etter en kort titt på Swagger.io leste jeg at en av forutsetningene var java 7. Da slo jeg det fra meg i første omgang. Så i romjulen fikk jeg litt ledig tid mellom alle familieselskapene. Derfor tenkte jeg at jeg skulle gjøre et forsøk.

Etter et søk på webben fikk jeg ikke treff på noe om Swagger og Dominodata, men jeg fant noe annet som så ut som en god start. På bloggen til Toby Samples fant jeg et utgangspunkt for REST på Domino. Bloggen hans finner du på urlen : https://tobysamples.wordpress.com

Han hadde brukt JAX-RS og implementert et eksempel i en OSGI-plugin. Han hadde ikke benyttet Swagger. Jeg tenkte, her kan jeg benytte lik fremgangsmåte, men integrere Swagger med Domino.

Hva er en OSGI-plugin?

Osgi-plugin er et stykke kode eller en komponent som programmeres i java og kan installeres i et java miljø. Du kan derfor finne dette innenfor mange områder i ditt dagligliv. Det finnes i bla. biler, mobiler og applikasjonsservere. Koden kan enkelt installeres på en server og lastes inn ved oppstart. Koden caches etter førstegangs bruk å gir derfor meget korte responstider og kan skalere godt. Oppdateringer og nye versjoner håndteres enkelt i et intuitivt brukergrensesnitt. Siden dette er en standard måte å implementere utvidelser på en serveren, er det heller ingen problemer med sikkerheten i java. En plug-in vil virke uten endringer i disse instillingene.

Du kan lese mer om OSGI på wikipedia : https://en.wikipedia.org/wiki/OSGi

Hvilke versjoner?

Neste utfordring var å finne riktige versjoner. For å kunne benytte nyeste versjon av Swagger fant jeg at 1.5.5 var veien å gå. I ettertid har jeg oppgradert til versjon 1.5.8. I tillegg gikk jeg for Wink 1.4 og Jacson 2.4.5. Nå gjensto det bare å se om jeg kunne få dette til å spille.

Jeg gikk i gang med Eclipse Mars 4.5.1 og satte opp miljøet. Er du interessert i hvordan dette gjøres finnes det mange beskrivelser på nettet. Toby Samples har en beskrivelse av dette på sine sider. Noen forutsetninger er at dette må kjøre på en Domino server versjon 9.1 eller høyere. Samtidig må du også ha en klientinstallasjon på 9.1 eller høyere.

Deretter begynte jeg å lage en plugin. Underveis forsto jeg raskt at det kunne bli problematisk å finne alle jarfiler Swagger trengte. Hvordan skulle jeg finne jeg finne alle avhengighetene? Maven hjalp meg, raskt fikk jeg et stort knippe jarfiler som måtte inn i pluginen. Så skrev jeg en enkel REST tjeneste som benyttet Swagger annotation. Dette gikk fort, og nå satt jeg plutselig med en OSGI plugin som benyttet Swagger APIet.

Dokumentasjon

En av de viktigste grunnene til å benytte Swagger er at du får god dokumentasjon. Her er det noen forutsetninger som må oppfylles. Har man benyttet Swagger på riktig måte får man en fil kalt swagger.json og en fil kalt swagger.yaml. Disse filene inneholder dokumentasjon av tjenestene dine. Hvilken du benytter er opp til deg, men det finnes et verktøy kalt Swagger UI som kan lese swagger.json og lage en testsuite av tjenestene dine. Det er denne testsuiten som gir en enkel dokumentasjon og testverktøy til tjenestene. Det er både intuitivt og gir oss en enkel mulighet til å teste tjenestene med en standard nettleser.

Swagger UI

Hvordan skal vi benytte Swagger UI er så det neste spørsmålet. Det finnes en demo av dette på http://petstore.swagger.io. Der er det mulighet for å få denne til å peke på din egen swagger.json. Det gjøres ved å lime inn urlen i feltet som vist på bildet under.

 

Swagger Petstore.png

 

Nytt problem oppstår. Har man tjenestene bak en firewall er de ikke tilgjengelig for validering. Swagger UI inneholder nemlig en mulighet for å kunne validere tjenestene dine. Her er det et problem vi må komme rundt.

Denne tjeneste ligger ute på internet. Er ikke tjenestene dine offentlig tilgjengelig, så vil det være umulig for valideringstjenesten å gi deg beskjed om tjenesten validerer. Du får en melding som vist på bildet under, et rødt ikon med ERROR.

    

Swagger Validation.png

  

 {"schemaValidationMessages":[{"level":"error","message":"Can't read from file http://www.somehost.xx/rest/v1/swagger.json"}]}

 I vårt tilfelle betyr det at løsningen vår er bak en firewall og vår swagger.json fil kan hverken hentes eller valideres. Ingen stor ting, men når vi har kommet så langt hvorfor ikke løpe linen helt ut.

 Swaggers validator

Siden dette er OpenSource kommer spørsmålet om vi også kan bake inn valideringskoden i vår plugin.

 Her begynner problemene. Det ser ut til at jarfilen støtter Java 7 og høyere. Kan jeg komme rundt det? Dette er en liten nøtt, men bør være mulig.

Siden dette er OpenSource henter jeg ned koden fra github og ser om det er mulig å kode oss ned til Java 6. Litt søking og koding så er vi i mål. Det tok noen få timer koding, men så spiller den med på Domino.

 Nå er det også mulig å validere swagger.json ved hjelp av vår plugin. Dermed har vi bevist at Domino og Swagger er en match. Vi kan enkelt både dokumentere og bevise at tjenestene våre validerer og virker. Dette gir en utvikler som skal benytte tjenestene et enkelt grensesnitt. All den informasjon vedkommende trenger for å benytte tjensten er dokumentert. Under ser du pluginen i aksjon. Legg merke til at den nederste seksjonen heter validator. Der ligger den som en del av tjenestene. Det gjør det mulig å validere Swagger tjenester internt og eksternt.

  

Swagger Validation 2.png

Testing og dokumentasjon sa du?

Så hvordan er det mulig å teste tjenesten og hvordan dokumenteres den?

Jeg laget en enkel tjeneste mot en navn og adressebok kalt fakeNAB. Dette er en base som inneholder over 40.000 persondokumenter. Hvilket er et godt testutgangspunkt og kan gi en pekepinn på hvor godt en slik tjeneste responderer.

Tjenesten skal brukes til å hente ut alle personer med etternavn eller fornavn som starter på den forbokstaven som søkes på.

Under ser du et eksempel på dokumentasjon av tjenesten og testmuligheter.  

Swagger Test.png

Her ser dere grensesnittet som dokumenterer tjenesten. Øverst ser vi tittelen Response Class(Status 200) som betyr OK Person(s) found. Verdiene som vil returneres er firstName, lastName og shortName. Disse returneres på formatet json (se application/json).

Så ser vi at tjenesten har et parameter som må med. Det er forbokstaven det søkes på. Finnes ikke personer med bokstaven det søkes på returneres en melding med statuskode 404 og teksten “Person not found”. Skulle det oppstå en feil på serveren vil man motta 500 Server error.

Hvordan testes så tjenesten og hvordan ser egentlig resultatet ut?

Under ser du et bilde av hvordan dette kan se ut. Vi har søkt etter alle personer som har en forbokstav i navnet sitt på a.

Swagger test 2.png

Først ser vi hvordan urlen for dette søket kan se ut. Legg merke til a, som står i slutten av urlen. Det er hva som plukkes opp av systemet og søkes etter. Response Body er ledeteksten til resultatet vi mottar. Dermed har vi også kunnet teste tjenesten fra dokumentasjonen. Dette er enkelt.

Responsetider
Etter alt dette arbeidet var det spennende å se på responsetidene. Ville det være tregt? Hvordan ville det respondere ved stort trykk? Etter at vi rullet ut vår swaggerplugin på testplattformen har vi bare høstet gode tilbakemeldinger. Konsumentene av tjenestene har vært overrasket over hvor raskt de får svar.

Å måle noe slikt blir relativt i forhold til forutsetningene til den enkelte server, utstyr, belastning, nettrafikk hva koden som utfører spørringen gjør og lignende.

Vi kan ikke kontrollere så mye utover koden som kjøres på serveren. Det er det eneste vi lager. Resten er forutsetninger og begrensninger andre setter på våre svarstider. Derfor tenkte jeg at jeg må ta tiden fra serveren mottar en forespørsel, til den sender avgårde svaret. Derfor klokket jeg dette med et filter, en kode snutt som fanger opp forespørsel og svar.

Svarene som kom tilbake var over alle forventninger. Vi var nede i under 10 millisekunder på flere av tjenestene. Dette klarte vi ved å holde koden vår på et minimum.

Til historien hører det også at vi benytter oss av Dominos egen tilgangskontroll og alle forespørslene er autentisert når de treffer serveren.

 

Om du vil fordype deg i dette og gjøre det på egenhånd vil kildene under være til hjelp.

https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X
https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X
https://github.com/swagger-api/swagger-ui
https://github.com/swagger-api/swagger-parser

Utviklingsverktøy
- Eclipse Mars 4.5.1

Nødvendig software
- Dominoserver v. 9.1 eller høyere
- Notesklient, Domino Designer v. 9.1 eller høyere

Kjekt å ha
- Domino Admin klient v. 9.1 eller høyere
- Soap UI v. 5.2.1 (denne kan settes opp til å teste tjenestene dine og simulere stor bruk)
- Notepad ++ v. 6.7.5

 

Vil du ha slike REST tjenester på din server hører vi gjerne fra deg

Happy coding :-)

Ketil

KONTAKT OSS

Vil du kontakte oss kan du sende mail på firmapost@item.no .

Nyhetsbrev

Ønsker du å motta vårt nyhetsbrev:

Meld meg på / Meld meg av