BSc- project EASY REST API EN DEMONSTRATOR IN3405 Data Archiving and Networked Services EWI MSc Maarten Hoogerwerf (DANS) dr. Arjan van Genderen (TU Delft) dr. Hans- Gerhard Gross (TU Delft) Georgi Khomeriki Roshan Timal 128291 4030087 11-06- 2012
1 Voorwoord Ter afsluiting van onze Bachelor opleiding aan de TU Delft wordt van ons verwacht om zelfstandig een project uit te voeren en deze tot een goed eind te brengen. In dit verslag beschrijven wij hetgeen we hebben gedaan en geleerd. Graag willen wij alle medewerkers van DANS bedanken voor de gezellige en leerzame tijd gedurende onze stage. Tevens willen wij onze begeleiders vanuit de TU, dr. Arjan van Genderen en dr. Hans- Gerhard Gross hartelijk bedanken voor hun inzet en feedback. Graag willen wij onze begeleider vanuit DANS, MSc Maarten Hoogerwerf, uitzonderlijk bedanken voor zijn zeer nuttige begeleiding gedurende het project. Hij heeft ons goed gestuurd om de zaken te bekijken vanuit een echt ingenieurs perspectief. 2
Inhoudsopgave 1 VOORWOORD... 2 2 SAMENVATTING... 5 3 INLEIDING... 6 3.1 DANS...6 3.2 EASY...6 3.3 DE OPDRACHT...6 4 PROBLEEMSTELLING EN ANALYSE... 7 5 ONTWERP... 8 5.1 AANPAK...8 5.2 REQUIREMENTS...8 5.3 WAAROM REST?...9 5.4 WAAROM ROA?... 10 5.5 KOPPELING MET HET HUIDIGE SYSTEEM... 11 5.6 ONTWERP VAN DE REST LAAG... 11 5.7 WAAROM ANDROID?... 12 5.8 ONTWERP VAN DE DEMONSTRATOR APP... 13 5.9 KWALITEITSWAARBORGING... 15 6 IMPLEMENTATIE...17 6.1 PLANNING VS. REALITEIT... 17 6.1.1 Requirements...17 6.1.2 Frameworks...18 6.1.3 Design keuzes...19 6.2 REFLECTIE OP DE IMPLEMENTATIE FASE... 21 6.2.1 Technische aspecten...21 6.2.2 Security aspecten...22 6.2.3 Juridische aspecten...22 6.2.4 Test suite...23 6.2.5 Feedback SIG...23 7 CONCLUSIE...25 8 AANBEVELINGEN...26 9 LITERATUUR...28 10 APPENDIX A OPDRACHTOMSCHRIJVING...29 11 APPENDIX B PLAN VAN AANPAK...31 11.1 INTRODUCTIE... 32 11.2 PROJECTOPDRACHT... 33 11.3 AANPAK EN TIJDSPLANNING... 35 11.4 PROJECTINRICHTING... 36 11.5 KWALITEITSWAARBORGING... 37 11.6 (PVA) BIJLAGE A TECHNISCHE ARCHITECTUUR EASY... 38 12 APPENDIX C ORIËNTATIEVERSLAG...39 12.1 INLEIDING... 39 12.2 EASY... 39 12.3 REST... 43 3
12.4 ROA... 45 12.5 RESTFUL FRAMEWORKS... 47 12.6 OVERIGE FRAMEWORKS... 50 12.7 ANDROID... 51 12.8 CONCLUSIE... 51 12.9 (OV) APPENDIX A - KEUZEMODEL GEBRUIKERSRECHTEN EASY... 52 13 APPENDIX D REQUIREMENTS ANALYSIS DOCUMENT API...53 13.1 INTRODUCTIE... 53 13.1.1 Doel van het systeem...53 13.1.2 Scope van het systeem...53 13.1.3 Doelen en succes-criteria van het project...53 13.1.4 Overzicht...54 13.2 HUIDIG SYSTEEM... 54 13.3 VOORGESTELD SYSTEEM... 55 13.3.1 Overzicht...55 13.3.2 Functionele requirements...56 13.3.3 Non-functionele requirements...58 13.3.4 Systeem modellen...59 13.4 WOORDENLIJST... 71 13.5 (RAD- API) APPENDIX A HTTP RESPONS CODES... 72 14 APPENDIX E REQUIREMENTS ANALYSIS DOCUMENT - CLIENT...73 14.1 VOORWOORD... 73 14.2 INTRODUCTIE... 73 14.2.1 Doel van de demonstrator...73 14.2.2 Scope van de demonstrator...73 14.2.3 Doelen en succes- criteria van het project...73 14.2.4 Overzicht...74 14.3 HUIDIGE IMPLEMENTATIES... 74 14.3.1 Grafisch weergeven van datasets op een kaart...74 14.3.2 Grafisch weergeven van datasets op een tijdlijn...75 14.4 VOORGESTELD SYSTEEM... 76 14.4.1 Grafisch weergeven van datasets op een kaart...76 14.4.2 Grafisch weergeven van datasets op een tijdslijn...77 14.5 SYSTEEM MODELLEN... 77 14.5.1 Scenarios...77 14.5.2 Use case model...78 14.5.3 Analysis object model...79 14.5.4 Dynamic model...80 15 APPENDIX F WEB APPLICATION DESCRIPTION LANGUAGE (WADL) BESCHRIJVING API...81 4
2 Samenvatting Data Archiving and Networked Services (DANS) is een instituut dat zich voornamelijk bezighoudt met het bevorderen van duurzame toegang tot digitale onderzoeksgegevens. EASY (Electronic Archiving SYstem) is het online archiveringssysteem dat hiertoe dient. EASY bevat veel datasets met data en metadata die op dit moment alleen toegankelijk zijn via de web interface. De opdracht voor deze BSc- stage was om een API te ontwikkelen (op basis van REST principes) die het voor externe applicaties mogelijk maakt te communiceren met EASY. Tevens moest een demonstrator app gebouwd worden die de mogelijkheden van API demonstreert. We begonnen het project met een oriëntatie fase, waarin we onderzochten wat mogelijke oplossingen konden zijn en welke tools we het beste konden gebruiken. Hierna volgde het ontwerp proces. De eerste stap in het ontwerp proces was het verzamelen en prioriteren van de requirements. Hiertoe hebben we verschillende stakeholders van het project benaderd en Requirements Analysis Documents (voor de server en voor de demonstrator) opgesteld. We hebben tevens gekeken of een op REST (Representational State Transfer) gebaseerde oplossing inderdaad de meest efficiënte was, dit bleek het geval te zijn. We hebben het REST principe verder geëxtrapoleerd en ons gecommiteerd aan het ROA (Resource Oriented Architecture) principe. We hebben de API als een zelfstandige module geimplementeerd die slechts communiceert met de business laag van EASY. De demonstrator is in staat te communiceren met de API en (meta)data daaruit op te vragen. Wij hebben veel tijd besteed aan het onderhoudbaar houden van het systeem. Dit deden we onder andere door veel tests te schrijven, gebruik te maken van standaarden en veel gebruikte frameworks/tools. Gedurende het project zijn er een aantal tegenslagen geweest die wij moesten overwinnen. Sommige tegenslagen waren van technische aard, zoals het configureren van de Spring context en de Maven dependencies of security overwegingen die ons parten speelden. Andere tegenslagen waren van juridische aard en slechts te verhelpen door toezeggingen van de jurist van DANS. Wij hebben naar ons gevoel het doel van de opdracht bereikt. De API is in staat om applicaties en toepassingen van derden te serveren met data uit EASY en de demonstrator is in staat om de potentie van een dergelijke API aan te tonen en de functies de valideren. DANS zou op de ingeslagen weg door moeten gaan en de API verder valideren en uitbouwen. Hiertoe hebben we een aantal aanbevelingen in dit verslag opgenomen. 5
3 Inleiding 3.1 DANS Data Archiving and Networked Services 1 (DANS) is een instituut van KNAW 2 en NWO 3. De voornaamste bezigheid van DANS is het bevorderen van duurzame toegang tot digitale onderzoeksgegevens. Een belangrijke doelstelling van DANS is het stimuleren van wetenschappelijke onderzoekers om gegevens duurzaam te archiveren en hergebruiken. Een voorbeeld van een dienst dat hiertoe dient is het online archiveringssysteem EASY 4. Tevens faciliteert DANS met het NARCIS 5 project toegang tot vele wetenschappelijke datasets, e- publicaties en andere onderzoeksinformatie in Nederland. DANS hanteert het principe Open als het kan, beschermd als het moet. Hiermee wordt bedoeld dat er getracht wordt data onder het Open Access principe te publiceren. DANS zorgt er met zijn dienstverlening en deelname in (inter)nationale projecten en netwerken voor dat de toegang tot digitale onderzoeksgegevens verder verbetert. 3.2 EASY Zoals eerder genoemd, is EASY (Electronic Archiving SYstem) het online archiveringssysteem van DANS. EASY bevat duizenden datasets op het gebied van sociale- en geesteswetenschappen. Sinds kort ondersteunt EASY ook andere disciplines. EASY faciliteert het online deponeren en beschikbaar maken van onderzoeksgegevens. Gebruikers van EASY kunnen op een gemakkelijke wijze zoeken naar bepaalde datasets en browsen door het archief. Naast de onderzoeksgegevens archiveert EASY tevens de metadata van deze gegevens. Deze metadata beschrijft de inhoud van de datasets. DANS gebruikt een gestandaardiseerd formaat voor de metadata genaamd Dublin Core 6. Voor een uitgebreidere uitleg van EASY verwijzen we de lezer naar het oriëntatieverslag (zie appendix C). 3.3 De opdracht De opdracht van DANS die wij voor deze BSc- stage hebben gekregen bestond uit twee globale delen. Het eerste deel bestond uit het ontwikkelen van een server (gebaseerd op REST architectuur principes) die machine- machine interactie mogelijk maakt met het EASY archief. Het tweede gedeelte van de opdracht bestond uit het implementeren van een Android 7 app die de mogelijkheden van de REST server demonstreert. 1 http://dans.knaw.nl/ 2 http://www.knaw.nl/ 3 http://www.nwo.nl/ 4 https://easy.dans.knaw.nl/ 5 http://www.narcis.nl/ 6 http://dublincore.org/ 7 http://www.android.com/ 6
4 Probleemstelling en analyse De voornaamste motivatie voor het ontwikkelen van een API voor EASY is de vraag van vele mensen binnen en buiten DANS om applicaties te ontwikkelen die gebruik kunnen maken van de data die in het EASY archief zit. Momenteel is EASY eigenlijk alleen bereikbaar via de web- interface. Er zijn wel een aantal API s gekoppeld aan EASY die bijvoorbeeld harvesting van metadata mogelijk maken (via het OAI- PMH 8 protocol) en onlangs is er ook een service bijgekomen die het mogelijk maakt om data automatisch te deponeren in EASY (via het SWORD 9 interface). Echter heeft EASY geen uniforme manier om resources die in EASY zitten beschikbaar te maken voor applicaties buiten EASY. EASY is een duurzaam archief dat voor de lange termijn beschikbaar moet zijn. Het is dus belangrijk dat EASY qua functionaliteit en code goed onderhoudbaar is. Men moet dus goed oppassen dat de omvang van het systeem niet uit de hand loopt. Er lopen binnen DANS veel projecten die toegevoegde functionaliteit vereisen van EASY. Tegenwoordig is het vaak zo dat deze dan ook daadwerkelijk in EASY worden geimplementeerd. Door een consistente API ter beschikking te stellen hoeft EASY niet belast te worden met specifieke functionaliteiten voor andere projecten maar kunnen deze buiten EASY worden geimplementeerd. Dit bevordert de modulariteit en zelfstandigheid van de systemen die gebouwd worden. De API moet het ook mogelijk maken om resources uit te wisselen met andere systemen. Resources moeten aangeboden kunnen worden via nieuwe kanalen zodat deze bijvoorbeeld gecombineerd kunnen worden met resources uit andere databronnen. Op dergelijke wijze kunnen nieuwe toepassingen worden ontwikkeld en kan er meerwaarde worden gecreëerd met de bestaande (meta)data. Om bovengenoemde redenen is bij DANS de wil ontstaan om een API te bouwen bovenop EASY die machine- machine interactie mogelijk maakt. 8 http://www.openarchives.org/oai/openarchivesprotocol.html 9 http://www.ariadne.ac.uk/issue54/allinson- et- al 7
5 Ontwerp 5.1 Aanpak We begonnen dit project met het bepalen van wat er nou precies moest gebeuren, dit deden we in eerste instantie aan de hand van de opdrachtomschrijving. Eventuele onduidelijkheden over de opdracht werden besproken met onze bedrijfsbegeleider. Vervolgens construeerden we een plan van aanpak (zie appendix B). In dat document werd beschreven hoe we het project zouden inrichten en wat we in globale lijnen gingen doen. Daarop volgend gingen we op zoek naar reeds bestaande software frameworks en tools die project ten goede zouden komen. Onze bevindingen hierover werden gedocumenteerd in het oriëntatieverslag. Voordat we konden beginnen met het daadwerkelijk implementeren van zowel de API als de demonstrator werden voor beide implementaties een RAD- document opgesteld. De inhoud van deze documenten werd gebruikt als leidraad tijdens de implementatie fase. Onze bevindingen over het algehele proces worden in dit document besproken en toegelicht. 5.2 Requirements De eerste stap in het ontwerp proces was het verzamelen en prioriteren van de requirements. Hiertoe hebben we verschillende stakeholders van het project benaderd. In eerste instantie was dat onze begeleider Maarten Hoogerwerf. Tevens hebben we veel gesprekken gevoerd met andere medewerkers van DANS. Ook hebben we een e- mail gestuurd naar alle medewerkers waarin we onze plannen kort toelichtten en een oproep deden tot het kenbaar maken van wensen betreffende de requirements en toepassingen van de API. We hebben vele ideeen en reacties ontvangen waaruit enkele toegevoegde requirements zijn voortgevloeid. Het belangrijkste doel van de API bleek de wens te zijn om de resources en functionaliteiten die voor gebruikers beschikbaar zijn via de web interface tevens beschikbaar te maken via de API maar dan voor machines/applicaties. De overige voornaamste requirements van de API zijn: security, uniformiteit en onderhoudbaarheid. De API moet bijvoorbeeld kunnen garanderen dat de data niet kwetsbaarder wordt ten gevolge van het gebruik van de API. Tevens moet de communicatie met de API op een uniforme (preferabel gestandaardiseerde) wijze verlopen. Uiteraard moet de API goed onderhoudbaar en testbaar zijn, aangezien deze API slechts een opzet is voor toekomstige implementaties en/of uitbreidingen. We hebben in eerste instantie de requirements opgesteld voor de API en daarna zijn we pas de requirements gaan analyzeren van de demonstrator aangezien deze sterk afhangen van hetgeen de API mogelijk maakt. Het doel van de demonstrator is om de mogelijkheden van de API goed te demonstreren en zoveel mogelijk van de functionaliteiten van de API gebruiken. De demonstrator moet dus aantonen dat degelijke functionaliteiten gebouwd kunnen worden. We hebben dus uiteindelijk twee Requirements Analysis Documents opgesteld, één voor de API en één voor de client (zie appendix D en E). 8
5.3 Waarom REST? Het ontwikkelen van een API voor EASY was gemakkelijk te verantwoorden. Echter was het de vraag waarom er per se voor een op REST gebaseerde aanpak gekozen moest worden. We hebben in de oriëntatie fase ons verdiept in de principes van REST en vooral gekeken naar wat de onderscheidende factoren zijn ten opzichte van overige architecturele inrichingen voor web services. In het boek RESTful Web Services (Richardson et al.) wordt gesteld dat web services globaal opgedeeld kunnen worden in drie categorieën op basis van architectuur, namelijk: RESTful resource oriented, RPC- style en REST- RPC hybrid. De RESTful resource oriented architectuur hebben we uitgebreid besproken in ons oriëntatieverslag (zie appendix C). Heel kort samengevat komt het erop neer dat REST het HTTP protocol benut op de manier zoals het oorspronkelijk door de bedenkers bedoeld was. Het gebruik van HTTP methoden, headers en respons codes staat centraal. REST biedt dus geen protocol overhead bovenop de huidige structuur van het web maar gebruikt hetgeen al jaren beschikbaar is en zichzelf al talloze malen heeft bewezen (waarvan het wereld wijde web het beste voorbeeld is). Het vaak (onbewust) gebruikte alternatief is de RPC- style van service architectuur. RPC staat voor remote procedure call, dit symboliseert de gedachtegang dat clients communiceren met servers door bepaalde procedures (van afstand) aan te roepen en de server het resultaat terug te laten sturen. Elk op RPC gebaseerde web service heeft behoefte aan nadere afspraken over de manier van communiceren. Contrasterend, hebben op REST gebaseerde services altijd dezelfde vocabulaire en manier van communiceren, namelijk HTTP. Vaak gebruiken op RPC gebaseerde services HTTP wel als onderliggend protocol voor de protocol maar wordt slechts een subset van de mogelijke aspecten gebruikt. Tevens wordt daar dan een eigen communicatie protocol bovenop geimplementeerd. Een dergelijke aanpak zorgt dus voor overhead in het communicatie protocol. Het derde alternatief van architectuur voor web services is een hybride variant van de twee overige varianten genaamd REST- RPC hybrid. Zoals de naam als suggereert combineert deze vorm van architectuur REST en RPC met elkaar. De daadwerkelijke invulling van de combinatie is aan de ontwikkelaars zelf. Een REST- RPC architectuur is vaak het resultaat van mensen die goede kennis hebben van web applicaties maar niet van de REST principes. Bij dergelijke systemen wordt vaak HTTP als communicatie medium gebruikt maar wordt nog steeds een RPC manier gebruikt om de server bepaalde taken uit te laten voeren. Ook dit alternatief leidt tot overhead (weliswaar minder dan RPC) in het communicatie aspect. De communicatie is wel enigzins uniform aangzien HTTP wordt gebruikt maar niet op het niveau dat bereikt zou kunnen worden. Voor daadwerkelijk uniforme communicatie zal men REST als enige van de drie mogelijkheden kunnen gebruiken. Dankzij het feit dat RESTful web services geen eigen manier van communiceren is er ook minder overhead in de code en documentatie nodig. Het principe bouwt echt op de oorspronkelijke gedachtegang van HTTP en gebruikt hetgeen al jaren voor handen is. We kunnen concluderen dat de op REST gebaseerde architectuur de meest degelijke oplossing is voor web services, met name voor services die machine- 9
machine interactie als doel hebben. De ontwikkelaars die de service willen gebruiken vanuit hun eigen applicatie kunnen dat doen door middel van HTTP communicatie en hoeven daarvoor niet een ander nieuw protocol uit te zoeken. 5.4 Waarom ROA? Nadat we voor onszelf verantwoord hadden waarom REST inderdaad de geschikte manier is om de web service in te richten besloten we de lat nog iets hoger te leggen en ons te commiteren aan de principes van ROA (Resource Oriented Architecture). We hebben ROA reeds uitgebreid besproken in het oriëntatieverslag (zie appendix C). Samenvattend kan gesteld worden dat REST (als beschreven in de dissertatie van R.T. Fielding) veel ruimte open laat als het gaat om daadwerkelijke implementatie en uitvoering. Dat is waar ROA om de hoek komt kijken en de open gelaten gebieden probeert in te vullen. Naast de reeds bestaande REST principes en constraints voegt ROA daar zijn eigen constraints aan toe. De toegevoegde constraints zijn: addressability, statelessness, connectedness en uniform interface. Deze constraints zijn tevens besproken in het oriëntatieverslag, dus we zullen er hier niet te diep op ingaan. Kort gezegd stelt de constraint van addressability dat elke resource addresseerbaar moet zijn via een eigen URI. Statelessness stelt dat elke request die een server ontvangt alle informatie moet bevatten om die request af te handelen. Het resultaat van een vorige request mag dus geen invloed hebben op het resultaat. Connectedness stelt dat resources gezien moeten worden als hypermedia die relaties hebben met andere resources en representaties. Deze relaties zijn een wezenlijk onderdeel van de resource zelf. De laatste constraint is de uniform interface. Deze stelt dat de communicatie met de server op een uniforme manier moet verlopen. In de praktijk komt het erop neer dat de HTTP methode stelt wat voor actie er uitgevoerd moet worden. Het adres van de HTTP request zegt op welke resource de betreffende actie uitgevoerd moet worden. Tevens kunnen de HTTP headers worden gebruikt om meta informatie over de uit te voeren actie mee te sturen. Om het ROA principe in perspectief te plaatsen naast de overige manieren van het ontwerpen van web services hebben we de onderstaande illustratie opgenomen. Figuur 1: Eén service op drie verschillende manieren. (RESTful web services) Alle drie de services uit het vorige figuur bieden dezelfde functionaliteiten, echter verbetert de usability naar rechts toe. Service A is een typische RPC- style service, alles wordt beschikbaar gesteld via een enkele URI. Deze service is niet addressable noch connected. Service B is addressable maar niet connected, er zijn geen relaties tussen de resources. Dit duidt waarschijnlijk op een REST- RPC 10
hybrid service. Service C is addressable en well- connected, resources hebben dus relaties met elkaar. Dit duidt op een RESTful service gebaseerd op ROA principes. Vanwege de concrete invulling van ROA op het REST principe en de heldere constraints hebben we gekozen om het ROA principe als leidraad te kiezen bij de inrichting van de server. Tevens passen de constraints goed bij de resources die in EASY zitten. Het kunnen addresseren van resources speelt bij veel projecten binnen DANS een rol, ook is connectedness van belang voor het linken van resources (dit is tevens iets wat heel erg speelt bij DANS). 5.5 Koppeling met het huidige systeem Nadat we de keuze hadden gemaakt voor een op ROA gebaseerde architectuur moesten we kijken hoe we de server zouden opzetten (met welke reeds bestaande technieken) en met name hoe we de koppeling zouden maken met het huidige systeem (EASY). We moesten ook verifiëren dat de keuze voor een op ROA gebaseerd systeem goed aansluit bij EASY. Dit bleek inderdaad het geval aangezien EASY in essentie gezien kan worden als een pool van resources (data, metadata, etc.). Het feit dat EASY gemoduleerd (three- tier) is opgezet heeft ons veel tijd bespaard. EASY is zo opgesteld dat elke module zijn eigen verantwoordelijkheid heeft. Aangezien wij een API moesten ontwikkelen hadden wij alleen een dependency nodig op de business laag van EASY. Via de business laag konden wij alle resources en informatie opvragen en eventueel bewerken. De business laag vroeg die resources dan weer op bij onderliggende modules. Ondanks het feit dat EASY veel modules bevat en heel veel code hebben wij ons alleen hoeven te beperken tot het communiceren met de services die de business laag biedt. Om zo veel mogelijk in lijn te blijven met de opzet van EASY hebben we besloten om veel dezelfde libraries, tools en API s te gebruiken. Wij hebben dus gekozen voor Maven 10 als build tool, eclipse 11 als ontwikkelomgeving, Spring 12 als koppel/configuratie systeem etc. Ook voor de ontwikkeling van de demonstrator hebben we gekozen voor de bovengenoemde systemen om ook die in lijn te houden met hetgeen binnen DANS gebruikt wordt. 5.6 Ontwerp van de REST laag Zoals we hadden beschreven in ons Plan van Aanpak (zie appendix B) hebben we de RESTful API als een alleenstaande module geimplementeerd die schematisch naast de huidige web UI staat en slechts gebruik maakt van de services uit de business laag en het domein model. Een klein deel van het totale architectuur plaatje is hieronder weergeven. Een volledige weergave van het architecturele ontwerp van EASY met de REST API daaraan toegevoegd is te zien in het Plan van Aanpak. 10 http://maven.apache.org/ 11 http://www.eclipse.org/ 12 http://www.springsource.org/ 11
Figuur 2: Een gedeelte van het ontwerp van EASY met daaraan toegevoegd de relatie met de RESTful API module (voor het volledige diagram zie Plan van Aanpak, Appendix B). Er moet hier wel bijgezegd worden dat het domein model gevisualiseerd is als zijnde losstaand van de business laag. Echter is de implementatie zo dat het domein model in de business laag zit op dit moment. Dit zou eigenlijk uitgesplitst moeten worden. Een belangrijke randvoorwaarde van onze API was dat we de functionaliteiten moesten realiseren op basis van hetgeen de business laag op dit moment te bieden heeft. Het was dus niet de bedoeling om speciale/nieuwe functies toe te voegen aan de business laag om de API te implementeren. We zijn er echter niet aan ontkomen om een paar kleine bugs te moeten opsporen en oplossen in EASY. Voor een overzicht van de methodes en resources die de REST API aanbiedt verwijzen we naar het Web Application Description Language 13 (WADL) document (zie appendix F). Dit is een op XML gebaseerd document dat de web service beschrijft op een manier die tevens interpreteerbaar is door machines. 5.7 Waarom Android? De voornaamste reden om de demonstrator te ontwikkelen voor het Android platform was omdat dit demonstreert dat de REST API platform onafhankelijk is. Bijna alle projecten van DANS hebben een (ouderwetse) website als front- end. De mogelijkheden van de API op een mobiel platform demonstreren leek ons 13 http://www.w3.org/submission/wadl/ 12
geschikt aangezien dat voor meer impact zal zorgen dan wederom een website die intern anders in elkaar zit. Een belangrijk technische factor bij de keuze voor Android was het feit dat we dan konden ontwikkelen in Java 14. De API is natuurlijk onafhankelijk van de taal waarin de client wordt geschreven, het zou dus passend zijn voor de demonstrator om een andere taal te kiezen voor deze. Echter, aangezien EASY in Java is ontwikkeld zal de API ook in Java ontwikkeld moeten worden, om dan in dezelfde lijn te blijven is het handig om de demonstrator tevens met dezelfde taal te ontwikkelen. Tevens is het zo dat wij goed bekend zijn met Java, dat scheelt dus ook weer in de tijd. 5.8 Ontwerp van de demonstrator app Een van de doelen van de demonstrator, was het valideren van de functies die de RESTful API aanbood. Om dit doel te verwezenlijken wordt er in de demonstrator via de API de data en metadata van datasets opgehaald. Tevens wordt er gebruik gemaakt van de search en advanced search algoritmes. De twee laatstgenoemde algoritmes zijn tevens beschikbaar gemaakt door de API. De demonstrator werd ook ontworpen om te laten zien dat door middel van de API het mogelijk werd om in andere omgevingen dan de web interface de data van EASY te gebruiken. Deze andere omgeving (zoals in de vorige paragraaf duidelijk is geworden) is in ons geval het Android platform. De werking van de demonstrator is als volgt: de demonstrator begint met het tonen van een inlogscherm. Met de gegeven gebruikersnaam en wachtwoord wordt bij elke request naar de API deze in de header gestopt en verstuurd. Vervolgens krijgt de gebruiker een zoekscherm te zien waar de keuze gemaakt kan worden ofwel de search ofwel de advanced search te gebruiken Als er een argument in het search veld wordt ingevoerd en daarop volgend op de knop view on map wordt gedrukt resulteert dit in een GET request op de URI: https://[host]/api/search?q=scheme=rd argument Bij de advanced search daarentegen wordt er een GET request uitgevoerd op de URI: https://[host]/api/advsearch?coverage=scheme=rd&attr=attrvalue&attr2=attrva lue &attrn=attrnvalue Waarbij attr een attribuut is waarop gezocht kan worden (bijvoorbeeld op titel) en attrvalue de waarde is behorend bij het attribuut. Bij zowel de search als de advanced search wordt er in de uri de argument scheme=rd toegevoegd, dit doen we omdat we willen forceren dat de datasets die we terugkrijgen als gevolg van een zoekquery daadwerkelijk coördinaten bevatten. Voor de werking van de demonstrator is het essentieel dat de datasets coördinaten bevatten aangezien deze in de Google Maps layer zullen worden weergeven. De zoekresultaten worden door middel van een markering weergeven op de kaart (zie figuur 3). Als de gebruiker op een markering klikt, wordt er een nieuwe activiteit gestart. Deze 14 http://www.oracle.com/nl/technologies/java/index.html 13
activiteit bevat drie tabs: respectievelijk de Overview, Description en Images tabs (zie figuur 4). Figuur 3: Locaties van datasets weergeven in Google Maps. In de Overview tab wordt een korte beschrijving van de dataset getoond. De inhoud van de Overview tab wordt gegenereerd met de response van de search, aangezien alle benodigde informatie te vinden is in de body van de response. De inhoud van de Description tab wordt bepaald door de metadata van een betreffende dataset. De metadata van een dataset kan worden opgevraagd door het versturen van een GET- request naar de RESTful- API op de volgende URI: https://[host]/api/{store-id}/metadata De body van de response wordt vervolgens geconverteerd naar een menselijk prettig ogend formaat. Bij de Images tab wordt de daadwerkelijke data van een dataset opgevraagd, echter willen we alleen de afbeeldingen van een dataset ophalen. Het ophalen en weergeven is dan ook tweedelig. In eerste instantie worden alle images van een dataset opgehaald door een GET- request uit te voeren op de URI: https://[host]/api/{store-id}/thumbnails Hierdoor krijgen we de namen van bestanden zoals die zijn opgeslagen in EASY. Vervolgens wordt de daadwerkelijke inhoud van een individueel bestand opgehaald, door een GET- request uit te voeren op: https://host/api/{store-id}/thumbnails/{thumbnail-id} De body van de response wordt geïnterpreteerd door de demonstator en vervolgens getoond in de Images tab. Dit proces wordt herhaald voor elk gevonden bestand. 14
Figuur 4: Tab activiteit waarbij de description tab is geselecteerd. 5.9 Kwaliteitswaarborging Gedurende het project hebben we getracht de op te leveren code zo kwalitatief en onderhoudbaar mogelijk op te zetten. Een aantal principes en design patterns die aan het licht kwamen bij het vak software engineering konden hier goed voor worden gebruikt. Tevens hadden we de keuze gemaakt om test- driven te ontwikkelen. We hebben dus veel tijd besteed aan het schrijven van unit tests. Gedurende de implementatie fase merkten we echter dat we te weinig tijd hadden om de test suites zodanig te schrijven als we van te voren hadden gepland. We hebben besloten om de server te voorzien van een goede test suite omdat deze de basis zal vormen voor toekomstige implementaties. De demonstrator daarentegen is precies hetgeen de naam al suggereert, slechts een demonstratie voor de mogelijkheden van de server. We hebben dus geen geautomatiseerde test suite geschreven voor de demonstrator. Hierdoor hadden we dus meer tijd voor de tests van de server en hebben we 99% line en branch coverage gerealiseerd. Om de code coverage te meten hebben we gebruik gemaakt van de Cobertura 15 plugin voor Maven. Het resultaat van de Cobertura meting is te zien in onderstaand figuur. 15 http://cobertura.sourceforge.net/ 15
Figuur 5: De test-coverage gemeten met de Cobertura plugin voor Maven. Een belangrijk onderdeel van het onderhoudbaar houden van de code is het schrijven van Javadoc 16 documentatie. We hebben Javadoc dus de nodige aandacht gegeven en ervoor gezorgd dat alle methoden degelijke Javadoc documentatie bevatten. Er moet hier wel bijgezegd worden dat Javadoc slechts een documentatie is van de implementatie en niet moet worden gezien als een handleiding voor het gebruik van de API. Om de leesbaarheid van de code te bevorderen hebben we gebruik gemaakt van een Maven plugin genaamd Checkstyle 17. Dit is een plugin die men via een XML configuratie de code kan laten checken op stijl fouten. In de configuratie wordt opgegeven welke stijl aspecten gecheckt moeten worden. We hebben bij het vak software kwaliteit & testen al een dergelijke configuratie gebruikt, vanwege de beperkte tijd is besloten om die ook voor dit project te gebruiken. Deze configuratie checkt de meest gangbare code practices. We hebben er uiteindelijk voor gezorgd dat de Checkstyle reports geen warnings en errors meer bevatten. Onderstaande illustratie bevat een klein deel van het Checkstyle resultaat. Figuur 6: Het resultaat van de Checkstyle plugin voor Maven. Wij hebben het gevoel dat de code goed onderhoudbaar is en van degelijke kwaliteit. Dit werd ook bevestigd door de eerste code review van SIG, hier zullen we later nog op terug komen. 16 http://en.wikipedia.org/wiki/javadoc 17 http://maven.apache.org/plugins/maven- checkstyle- plugin/ 16
6 Implementatie 6.1 Planning vs. realiteit Hetgeen we met de opdrachtgever zijn overeengekomen bij aanvang van het project bleek ambitieuzer te zijn dan gedacht. Ondanks het feit dat de opdracht voor drie personen was geformuleerd en wij slechts met zijn tweeën waren konden we niet goed inschatten wat realiseerbaar was. Zoals wel gewoonlijk is bij IT- projecten verkeken wij ons op de verhouding van hoeveelheid werk en beschikbare tijd. Tevens hebben we veel onvoorziene problemen moeten oplossen. Jammer genoeg hebben we dus bepaalde aspecten die we wel hadden ingepland niet uit kunnen voeren. In dit hoofdstuk zullen we daar wat verder over uitwijden. Ook zullen we ingaan op de keuzes die we hebben gemaakt betreffende bepaalde tools/frameworks/libraries die wij hebben gebruikt om het project te realiseren. Bij deze keuzes zijn we uitgegaan van onze eigen kennis/ervaring en hetgeen DANS reeds gebruikt. 6.1.1 Requirements Om binnen de gegeven tijd het project af te ronden moesten er concessies gedaan worden over welke functionele requirements geïmplementeerd werden en welke niet. Het MoSCoW document dat was opgesteld (naar aanleiding van de behoeftes van de klant) in het RAD document (zie appendix D) hielp bij het maken van een selectie van requirements die uiteindelijk wel in ons tijdsbestek pastten. Elk van de requirements opgedeeld in Must have zijn geïmplementeerd behalve de requirement De server moet expliciet in de respons headers meesturen of een resource cacheable is en wanneer de resource voor het laatst is gewijzigd. Deze requirement is niet geïmplementeerd omdat in EASY niet kan worden bepaald wanneer een resource voor het laatst is gewijzigd. Dit is uiteraard essentieel voor het bepalen of een resource cacheable is of niet. De requirements betreffende het sturen van PUT en POST- requests in Should have zijn niet geïmplementeerd, de reden hiervoor wordt nader toegelicht in de paragraaf Security aspecten. Andere requirements in Should have die niet zijn geïmplementeerd, zijn de requirements gerelateerd aan de zogenaamde permission requests, dit was voornamelijk te wijten aan tijdgebrek. De resterende requirements in Should have zijn wel geïmplementeerd, deze omvatten onder andere het intact houden van de lucene zoek- syntax en de adresseerbaarheid van elementen van een dataset. De requirements betreffende gebruikersovereenkomsten zijn niet geïmplementeerd. De voornaamste reden van het niet implementeren van deze requirements was het gebrek aan tijd. De laatsgenoemde requirements vielen onder Could have. Een requirement van Could have die echter wel is geïmplementeerd is het opvragen van resources in meerdere formaten. De requirements die zijn opgedeeld in Won t have zijn niet geïmplementeerd. De opdrachtgever achtte deze requirements niet van dermate belang (immers, deze waren ingedeeld in Won t have ). Voor de requirements van de demonstrator, beschreven in desbetreffende Requirements Analysis Document (appendix E), is de voornaamste requirement 17
dat niet is geïmplementeerd het combineren van verschillende databronnen met de data die beschikbaar is gesteld door de RESTful API. Elk ander requirement opgelegd door de opdrachtgever betreffende de demonstrator is wel geïmplementeerd. Wat betreft de non- functionele requirements, is het schrijven van een handleiding voor de API in verband met de resterende tijd niet gelukt. Er is echter wel een WADL document die de API beschrijft. Tevens is om de bovenstaande reden het niet gelukt om de API en eventueel de demonstrator te stresstesten. Voor zover mogelijk hebben we wel het ROA- principe aangehouden (het implementeren van de cacheability nagelaten). 6.1.2 Frameworks Alvorens te beginnen aan de implementatie fase hadden we ons georiënteerd op de reeds bestaande frameworks die we zouden kunnen gebruiken voor het project. Frameworks zijn vaak goed getest en van goede kwaliteit, deze kunnen dus veel tijd en werk besparen. Een aantal framework keuzes zijn zeer productief gebleken maar een aantal bleken gedurende de implementatie fase onbruikbaar. Voor die frameworks hebben we dus alternatieven moeten gebruiken of, in een enkel geval, de functionaliteit zelf moeten schrijven. De keuze voor de op JAX- RS 18 (zie oriëntatieverslag, appendix C) specificatie gebaseerde Jersey 19 framework heeft ons veel tijd bespaard. Het stelde ons in staat om de server in te richten door gebruik van annotaties. Echter hadden we gepland om de bijbehorende Jersey client te gebruiken voor de demonstrator. Dit is niet strikt noodzakelijk aangezien elke client (met HTTP voorzieningen) dienst zou kunnen doen, echter leek het ons tijd besparender om ook hiervoor Jersey te gebruiken. Met deze Jersey client zou de communicatie opgezet worden met de server. Jammer genoeg bleek deze client niet compatible te zijn met de virtuele machine (genaamd Dalvik VM 20 ) die draait op Android. We hebben vervolgens moeten kiezen om Spring- Android 21 te gebruiken voor de Android app. Ook hadden we initieel de keuze gemaakt om geen gebruik te maken van de Jersey- Test- Framework aangezien we wilden dat de unit tests onafhankelijk zouden zijn van de gebruikte REST framework. Vooral vanwege de JAX- RS ondersteuning zou DANS in de toekomst zeer gemakkelijk kunnen overstappen op een alternatieve implementatie. We wilden zekerheid hebben dat in een dergelijke situatie de test suite nog steeds zou functioneren. Daarom hadden we de keuze gemaakt om de onafhankelijke REST- assured 22 framework te gebruiken. Echter kwamen we tijdens het schrijven van unit tests erachter dat deze zeer weinig faciliteiten had voor het schrijven van unit tests en vooral gespits was op het ontwikkelen van integratie tests. Bij test- driven ontwikkeling zijn unit- tests cruciaal dus hebben we besloten om alsnog Jersey- Test- Framework te gebruiken. Ondanks alles zijn we er alsnog in geslaagd om de tests framework onafhankelijk te houden. 18 http://jsr311.java.net/ 19 http://jersey.java.net/ 20 http://www.dalvikvm.com/ 21 http://www.springsource.org/spring- android/ 22 http://code.google.com/p/rest- assured/ 18
Nog een belangrijke keuze die we bij aanvang hadden gemaakt was het gebruik van de PowerMock 23 framework met als onderliggend framework EasyMock 24. Deze keuze hadden we gemaakt omdat we al bekend waren met deze frameworks en dit ook de frameworks zijn die gebruikt worden in de test- suite van EASY. Echter bleek tijdens het schrijven van de tests dat de Jersey- Test- Framework niet compatible is met deze mocking frameworks. We moesten dus overstappen naar het (minder krachtige) mockito 25 framework om objecten te mocken in onze unit tests. De laatste framework keuze die uiteindelijk niet de implementatie heeft bereikt was om JiBX 26 te gebruiken voor het omzetten van java objecten naar XML structuren. EASY maakt tevens gebruik van JiBX. Echter bleek deze veel te complex te zijn voor de simpele doeleinden waarvoor wij het nodig hadden. We hebben dus om tijd te besparen besloten om JiBX niet te gebruiken. DANS had slechte ervaringen met JiBX dus we vonden het weglaten van deze niet heel erg. Als alternatief hebben we zelf een (uiterst) simpele XML converter geschreven. We hebben het zo opgezet dat het relatief gemakkelijk is om deze in de toekomst te vervangen door een alternatieve implementatie of framework. 6.1.3 Design keuzes Zoals gewoonlijk bij IT projecten is het ontwerp van de applicaties gedurende de implementatie fase een aantal keer bijgesteld. Dit is inherent aan een agile manier van werken. Verrassend genoeg zijn de ontwerp keuzes die we voor de implementatie fase hadden gemaakt wel in grote lijnen intact gebleven. De grootste verschillen zitten echt op het detail/implementatie niveau. We hebben de complexiteit van bepaalde functionaliteiten onderschat waardoor een aantal klassen iets ingewikkelder zijn geworden dan gepland. Echter hebben we de complexiteit enigzins vereenvoudigd door goed gebruik te maken van objectgeoriënteerde principes. In het Requirements Analysis Document van de API hebben we een klassediagram opgenomen die het globale ontwerp weergeeft. Onderstaand figuur illustreert de uiteindelijke implementatie van dat ontwerp. 23 http://code.google.com/p/powermock/ 24 http://easymock.org/ 25 http://code.google.com/p/mockito/ 26 http://jibx.sourceforge.net/ 19
Figuur 7: Een gedeelte van het klassediagram van de uiteindelijke API. Bovenstaand klassediagram toont het belangrijste deel van de API implementatie. Dit zijn de daadwerkelijke resource klassen die een request binnenkrijgen en daarvoor een respons genereren. Om dat te doen gebruiken ze tevens allerlei utility klassen die wij hebben geschreven, echter hebben we deze niet opgenomen in het diagram om het overzicht te bevorderen. Een opvallende ontwerp keuze waar uiteindelijk van zijn afgestapt is het gebruik van Persistent Identifiers 27 voor het identificeren van resources. Om de URI s die wijzen naar resources zo consistent mogelijk te houden leek ons het gebruik van Persistent Identifiers een goed idee. Echter bleek dat de business laag van EASY niet op basis van dergelijke identifiers de bijbehorende resources kan vinden. Daarvoor zouden we dus functionaliteit in de business laag moeten bijbouwen, hetgeen we wilden voorkomen. Tevens bleek het zo te zijn dat sommige datasets deze Persistent Identifiers nog niet hebben, die zouden dus niet adresseerbaar zijn met een dergelijke aanpak. Na rondvraag bij de beheerders en ontwikkelaars van EASY begrepen we dat de interne store ID s van objecten tevens een redelijk permanent karakter hebben. We hebben dus de store ID s gebruikt voor het adresseren van resources. 27 http://www.dans.knaw.nl/content/categorieen/diensten/persistent- identifier 20