EWI. BSc- project EASY REST API EN DEMONSTRATOR IN3405. Data Archiving and Networked Services

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 128291

11-‐06-‐2012

Roshan Timal 4030087

10-‐07-‐2012

Roshan Timal – 4030087 Georgi Khomeriki – 1282921

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

10-‐07-‐2012


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

10-‐07-‐2012

12.4 12.5 12.6 12.7 12.8 12.9


ROA .................................................................................................................................................... 45 RESTFUL FRAMEWORKS................................................................................................................. 47 OVERIGE FRAMEWORKS .................................................................................................................. 50 ANDROID ............................................................................................................................................ 51 CONCLUSIE ......................................................................................................................................... 51 (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

10-‐07-‐2012


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

10-‐07-‐2012


3 Inleiding

3.1 DANS Data Archiving and Networked Services1 (DANS) is een instituut van KNAW2 en NWO3. 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 EASY4. Tevens faciliteert DANS met het NARCIS5 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 Core6. 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 Android7 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

10-‐07-‐2012


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-‐PMH8 protocol) en onlangs is er ook een service bijgekomen die het mogelijk maakt om data automatisch te deponeren in EASY (via het SWORD9 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

10-‐07-‐2012


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

10-‐07-‐2012


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

10-‐07-‐2012


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

10-‐07-‐2012


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 Maven10 als build tool, eclipse11 als ontwikkelomgeving, Spring12 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

10-‐07-‐2012


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 Language13 (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

10-‐07-‐2012


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 Java14. 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

10-‐07-‐2012


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

10-‐07-‐2012


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 Cobertura15 plugin voor Maven. Het resultaat van de Cobertura meting is te zien in onderstaand figuur. 15 http://cobertura.sourceforge.net/

15

10-‐07-‐2012


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 Javadoc16 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 Checkstyle17. 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

10-‐07-‐2012


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

10-‐07-‐2012


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-‐RS18 (zie oriëntatieverslag, appendix C) specificatie gebaseerde Jersey19 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 VM20) die draait op Android. We hebben vervolgens moeten kiezen om Spring-‐Android21 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-‐assured22 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

10-‐07-‐2012


Nog een belangrijke keuze die we bij aanvang hadden gemaakt was het gebruik van de PowerMock23 framework met als onderliggend framework EasyMock24. 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) mockito25 framework om objecten te mocken in onze unit tests. De laatste framework keuze die uiteindelijk niet de implementatie heeft bereikt was om JiBX26 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

10-‐07-‐2012


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 Identifiers27 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

10-‐07-‐2012


6.2 Reflectie op de implementatie fase In dit gedeelte zullen we ingaan op de dingen die goed en/of slecht gingen tijdens de implemenatie fase van de server en de demonstrator. Naast problemen van technische aard kwamen we ook problemen tegen van juridische aard. Security overwegingen hebben ook een rol gespeeld in bepaalde keuzes om sommige functionaliteiten niet te implementeren. 6.2.1 Technische aspecten Toen we klaar waren om te beginnen met de implementatie fase was het eerste dat we moesten doen het opzetten van de ontwikkelomgeving. Dit bleek gecompliceerder dan gedacht en nam dus veel tijd in beslag. EASY wordt binnen DANS ontwikkeld in een virtuele omgeving die lijkt op de productie omgeving. Dus we konden beginnen met de virtuele machine die gebruikt wordt binnen DANS. Echter maakt EASY gebruik van een groot aantal complexe tools en services waar wij niet zo bekend mee waren (bijv. Fedora, Solr, LDAP etc.). Het is een hele uitdaging gebleken om de omgeving correct te configureren en EASY op te starten. Wel moeten we hierbij zeggen dat we veel hebben geleerd van het opzetten van al deze dingen. Toen we eenmaal de ontwikkelomgeving en EASY aan de praat hadden, hadden we vrij snel een REST inteface opgezet. Dankzij de frameworks die wij gebruikten konden we veel dingen relatief snel implementeren. Een fout die wij hadden gemaakt in het begin was de API te injecteren in EASY (m.b.v. Spring) zodanig dat deze opstart wanneer de web-‐interface wordt opgestart. Dit werkte welliswaar prima tijdens de ontwikkeling van de API en de demonstrator maar toen we de API op de testserver van DANS wilden testen bleek het niet handig om heel EASY te herdeployen omwille de API. Het was de bedoeling dat de API onafhankelijk opgestart kon worden van de web-‐interface (wat achteraf zeer logisch leek). DANS gebruikt een Apache Tomcat28 server en wij moesten zorgen dat deze onze API zou opstarten binnen zijn eigen web-‐container. In de praktijk betekende dit voor ons een enorme berg configuratie en instellingen die aan de API toegevoegd moesten worden. Dit heeft ons zeer veel tijd gekost aangezien we dit niet hadden geanticipeerd. Iets wat ons ook veel tijd heeft gekost is de implementatie van de (advanced) search resources. Er is binnen DANS geen documentatie betreffende deze functionaliteit en geen van de ontwikkelaars wist hoe het werkte. Wij moesten dus vanuit de EASY code zelf uitzoeken hoe de zoek functionaliteit werkt. Na een lange zoektocht bleek het opgezet te zijn met een grote hoeveelheid reflectie technieken die het geheel ingewikkelder maken dan nodig. Door het gebruik van reflectie had de IDE (eclipse) ook geen grip op hetgeen de code doet en kon dus geen hulp bieden bij het uitvogelen van de functionaliteit. Het EASY ontwikkelteam was het met ons eens dat dit te complex was opgezet en vond ook dat dit een gedeelte is van EASY dat gerefactored mag/moet worden. De bovengenoemde punten waren eigenlijk de enige technische knelpunten gedurende dit project. De eerder genoemde frameworks hebben ons veel tijd en werk bespaard en ervoor gezorgd dat wij iets bruikbaars en werkends konden opleveren. De (three-‐tier) opzet van EASY heeft ons ook goed geholpen en ons ontwerp bleek goed bruikbaar gedurende de implementatie. 28 http://tomcat.apache.org/

21

10-‐07-‐2012


6.2.2 Security aspecten We hebben veel gesprekken gevoerd met betrekking tot security met de security manager (dr. Henk Koning) van DANS. We merkten aan deze gesprekken dat DANS security zeer serieus neemt. Een security requirement van de API was dat de resources van EASY niet kwetsbaarder zouden worden voor aanvallen van hackers. De API moet kunnen garanderen dat het minstens net zo veilig is als de huidige web-‐interface van EASY. Het eerste aspect dat hieronder valt is authenticatie van gebruikers. Aangezien de API stateless is, vindt authenticatie plaats bij elke request. Elke request die binnenkomt bevat dus de informatie om de gebruiker te authenticeren. Als deze informatie niet bij de request zit dan kunnen alleen de acties worden uitgevoerd die zijn toegestaan voor anonieme gebruiker (bijv. zoeken, metadata bekijken, etc.). Tevens is het zo dat de API alleen acties uitvoert waartoe de geauthenticeerde gebruiker geauthorizeerd is. Ten behoeve van de security was ook de requirement opgesteld om communicatie met de API alleen over een SSL29 verbinding (HTTPS) toe te staan. Hierdoor kan gesteld worden dat het ondoenlijk is voor een (kwaadwillende) derde partij om de communicatie tussen een client en de API server af te tappen. Als DANS besluit de API daadwerkelijk voor de buitenwereld open te zetten komen er wat grondigere problemen om de hoek kijken. Namelijk, hoe beveilig je gebruikers van bijvoorbeeld EASY apps die ontwikkeld zijn door kwaadwillende ontwikkelaars. De app zou bijvoorbeeld in staat zijn om de inlog gegevens van gebruikers af te tappen en deze gebruiken voor malafide doeleinden. Dit is een zeer grondig probleem waarop niet een simpel doorslaggevend antwoord kan worden gegeven. Een oplossing zou een combinatie van verschillende security principes moet bevatten. Bijvoorbeeld het gebruik van OAuth30 als authenticatie methode en/of het alleen toestaan van goedgekeurde (d.m.v. code signing31) applicaties om te communiceren met de API van EASY. We zullen hierop terugkomen bij onze aanbevelingen. Er is in overleg met de stakeholders ook besloten om vanwege security overwegingen de mogelijkheid om data toe te voegen of te manipuleren in EASY niet te ondersteunen vanuit de API. Dit betekent dat de API geen PUT en POST requests afhandelt. Het is voor DANS verstandiger om eerst te kijken hoe de API zal functioneren zonder dergelijke functies. De opzet van de API is zodanig dat deze functies zonder veel (technische) moeite toegevoegd kunnen worden. 6.2.3 Juridische aspecten Gedurende de ontwerp fase hadden we ons grotendeels verkeken op factoren van niet-‐technische aard die meespelen bij het opzetten van een dergelijk systeem. Het is gebleken dat bepaalde juridische belemmeringen grote invloed kunnen hebben op hetgeen gerealiseerd kan worden. Het probleem is namelijk dat gebruikers die vanuit de web-‐interface bestanden downloaden bij elke download een aantal juridische overeenkomsten moeten accorderen door middel van een vinkje (‘I agree….’). Een voorbeeld van een dergelijk bericht in EASY is weergeven in onderstaand figuur. 29 http://nl.wikipedia.org/wiki/Secure_Sockets_Layer 30 http://oauth.net/ 31 http://nl.wikipedia.org/wiki/Code_signing

22

10-‐07-‐2012


Figuur 8: Juridisch bericht dat gebruikers moeten accorderen alvorens te mogen downloaden.

Aangezien de REST API geen user interface heeft maar wel bestanden kan aanbieden wordt het dus mogelijk voor mensen om te downloaden zonder de overeenkomst te accorderen. Na veel gesprekken met de betrokken medewerkers (waaronder de jurist van DANS) is gebleken dat DANS al eerder de intentie had om het accorderen van de overeenkomsten eenmalig te doen bij de registratie van gebruikers. Echter is dit nog niet doorgevoerd maar het is iets waar DANS naartoe wil. Aangezien we hebben besloten om de API voorlopig alleen binnen DANS beschikbaar te maken heeft men tijd om daar een geschikte juridische oplossing voor te vinden. 6.2.4 Test suite Hoewel we zeer trots zijn op het feit dat we bijna 100% line en branch coverage hebben bereikt met onze unit tests moeten we wel eerlijk toegeven dat een dergelijke coverage niet per se betekent dat fouten in de code altijd gevonden zullen worden. Het is namelijk zo dat unit tests de componenten van het systeem isoleren en afzonderlijk testen. Al zijn deze componenten goed getest en doen ze individueel precies hetgeen ze moeten doen bestaat de reële kans dat het systeem als geheel alsnog niet correct functioneert. Om het systeem als geheel te testen zouden integratie tests ontwikkeld moeten worden. Dit hadden wij initieel ook gepland maar vanwege tijdstekort hebben we dit uiteindelijk niet kunnen doen. Wij hebben hier bewust voor gekozen omdat we hadden gemerkt dat de backend van EASY zeer complex is. Het opzetten van goede (duurzame) integratie tests zou buiten het domein van dit project vallen gezien de tijd die we hadden voor de stage. 6.2.5 Feedback SIG De feedback die wij hebben ontvangen van SIG op de eerste versie van onze code was zeer lovend. SIG bevestigde dat onze code goed onderhoudbaar was opgezet en scoorde 4 van de 5 sterren op hun beoordelingsschaal. Hier waren wij zeer tevreden mee, echter was er ook het een en ander aan te merken op onze code. Er werden twee punten genoemd door SIG die beter konden in onze

23

10-‐07-‐2012


implementatie. Dit was Module Coupling en Unit Size. Met Module Coupling werd bedoeld dat er bepaalde klassen waren die te veel verantwoordelijkheid hadden en moesten worden uitgesplitst. Met Unit Size werd bedoeld dat er bepaalde methoden waren die te lang waren, deze moesten tevens worden uitgesplitst. Wij hebben de aanbevelingen uit de feedback verwerkt in onze implementatie.

24

10-‐07-‐2012


7 Conclusie

Terugkijkend op het project zijn wij zeer tevreden met hetgeen wij uiteindelijk hebben opgeleverd. We hebben weliswaar op bepaalde onderdelen en requirements concessies moeten doen vanwege tijdsgebrek en/of security/juridische overwegingen. Het doel om een API te implementeren die het mogelijk maakt voor externe applicaties om (meta)data uit EASY te gebruiken is gerealiseerd. Het doel om de mogelijkheden van deze API vervolgens te demonstreren aan de hand van een mobiele app is tevens goed afgerond. We hebben gedurende dit project veel geleerd over de resource oriented manier van software architectuur. De geleerde lessen hebben we ook overgedragen aan medewerkers van DANS. We hebben gemerkt dat andere projecten binnen DANS (bijv. MIXED) nu ook beginnen met het implementeren van een op REST principes gebaseerde interface. Hierbij heeft men een beroep gedaan op de kennis en ervaringen die wij hebben opgedaan gedurende dit project. Aangezien DANS (voornamelijk) een digitaal data-‐archief is dat zich vooruitstrevend positioneert, denken wij dat het aanbieden van data via dergelijke kanalen een wezenlijk onderdeel zal vormen van de diensten van DANS in de toekomst. Wij kunnen concluderen dat DANS met hetgeen afgeleverd is een solide basis heeft om zich verder te kunnen oriënteren op het gebied van dergelijke (API) diensten. Voor de voortzetting van dit project binnen DANS doen we in het volgende hoofdstuk een aantal aanbevelingen op basis van onze ervaringen en bevindingen.

25

10-‐07-‐2012


8 Aanbevelingen

Gedurende het project hebben we veel bevindingen gedaan waar voortzetting van dit project zeer gebaat bij zou kunnen zijn. Onze bevindingen willen we verwoorden in aanbevelingen voor DANS. In eerste instantie willen we ingaan op de aspecten van het project die wij niet af hebben gekregen. Het zou bijvoorbeeld een goed idee zijn voor DANS om de simpele XML converter die wij hebben geschreven in de API te vervangen door een andere implementatie. Dit moet gedaan worden ter bevordering van de uitbreidbaarheid en schaalbaarheid van de API. De code is zodanig dat deze vervanging zonder al te veel technische problemen uitgevoerd kan worden. Verder zouden we DANS aanraden om de cacheability constraint van ROA strict op te volgen. Wij hebben dit niet kunnen doen omdat EASY niet voor alle resources de mogelijkheid biedt om op te vragen wanneer ze voor het laatst zijn gewijzigd. De cacheability constraint kan veel bandbreedte en rekentijd besparen voor zowel de server als de client. Iets wat zeer belangrijk is voor de onderhoudbaarheid van de API is het ontwikkelen van integratie tests. Wij hebben dit niet kunnen doen vanwege de complexe integratie omgeving die opgezet zou moeten worden. Wij zouden DANS aanraden om dit wel te realiseren. Als DANS zich commiteert aan het daadwerkelijk via de API aanbieden van alle functionaliteit die vanuit de web interface beschikbaar is. Moet het mogelijk zijn om (meta)data te kunnen toevoegen en te manipuleren met de API. Hiervoor moeten de HTTP methodes PUT, POST en DELETE worden ondersteund. De opzet zit al in de huidige API hiervoor, echter hebben wij de functies niet ingevuld vanwege security overwegingen. Op het gebied van security raden wij aan om de authenticatie met het OAuth protocol te laten verlopen. Hierbij hoeft de gebruiker van een applicatie die geschreven is door een derde partij niet zijn inloggegevens aan die partij te onthullen. De gebruiker wordt dan doorgestuurd naar een inlog module van DANS en wordt na het inloggen teruggestuurd naar de applicatie waar hij mee bezig was. Echter moet hier wel bijgezegd worden dat het voor een degelijk niveau van security waarschijnlijk ook verstandig is om alleen applicaties van vertouwde partijen toe te laten (d.m.v. code signing). Voorlopig is het wijs om op de ingeslagen weg verder te gaan en de API binnen DANS te testen. Vervolgens kan er gekeken worden hoe deze uitgebreid kan worden en aan de buitenwereld kan worden aangeboden. Ook moet DANS kijken naar het juridisch beleid en met name de momenten waarop gebruikers overeenkomsten moeten accorderen. Wij hebben niet de juridische kennis om hier een concrete aanbeveling voor te doen maar als de accordering op één moment gedaan kan worden en in toekomst overgeslagen dan zou dat veel schelen voor de API. Vanuit implementatie gerichte aanbevelingen willen we benadrukken dat het niet uit maakt welk framework wordt gebruikt voor de REST API zolang deze maar de JAX-‐RS specificatie ondersteunt. Dit zorgt voor onafhankelijkheid voor de gebruikte framework aangezien het ene JAX-‐RS framework kan worden vervangen voor het andere zonder de code te wijzigen. Tevens is JAX-‐RS

26

10-‐07-‐2012


onderhand een standaard geworden voor het implementeren van RESTful web services in Java. Ook zou het veel werk in de toekomst schelen als DANS de Spring en Maven configuratie van EASY zou opschonen en waar nodig corrigeren. Om een voorbeeld te noemen: ons project maakt vanuit de code enkel gebruik van de business laag, echter om het project op de server werkend te krijgen moesten we dependencies en configuraties toevoegen aan modules waar wij geen directe dependencies op (zouden moeten) hebben anders werkt het simpelweg niet. Verder willen we aanraden om de zoekfunctionaliteiten in de EASY backend te refactoren. En dan het liefst zodanig dat er geen reflectie wordt toegepast bij de implementatie. Wij zijn van mening dat reflectie alleen zou moeten worden gebruikt wanneer het ‘echt niet anders kan’. En in dat geval moet de betreffende code zeer helder en uitgebreid gedocumenteerd worden. Geen van de DANS medewerkers kon ons namelijk vertellen hoe de zoek functionaliteit werkt. Deze was namelijk geimplementeerd door een medewerker die niet meer bij DANS werkt. Het zou ook de bruikbaarheid van de API ten goede komen als DANS meer informatie kon opnemen in EASY over relaties tussen resources. Kortgezegd, DANS moet aandacht besteden aan linked resources, zodat relaties tussen resources transparant en bruikbaar worden. De ROA constraint van connectedness hebben wij door de afwezigheid van deze realties niet strict kunnen implementeren. Tevens zou een concretere scheiding van de business laag en het domein model volgens ons de onderhoudbaarheid ten goede komen. Op dit moment zitten de domein klassen in de business laag. Onze laatste aanbeveling is om de functionaliteiten die in de business laag zitten uit te breiden en/of generieker te maken. Om een voorbeeld te noemen: de business laag biedt geen mogelijkheid om te zoeken op intervallen van bijvoorbeeld tijdsperiodes. Dergelijke dingen zouden de bruikbaarheid van de API ten goede komen. Ook zou men na het grondig testen van onze API kunnen kijken welke additionele functionaliteiten nodig kunnen zijn voor toekomstige toepassingen van de API.

27

10-‐07-‐2012


9 Literatuur

[1] - Fielding RT. Architectural styles and the design of network-based software architectures. PhD Thesis, University of California, Irvine, 2000. [2] -‐ L. Richardson and S. Ruby. RESTful Web Services. O’Reilly Media, Inc., May 2007. [3] -‐ JSR311 – JAX-RS: Java API for RESTful Web Services http://java.net/projects/jsr311 [4] -‐ M. Hadley and P. Sandoz. JAXRS: Java API for RESTful Web Services. JSR, JCP, September 2009. [5] – V. Vettrivel. RESTful Web services with Apache Wink, Part 3: Apache Wink and the REST, April 2010 [6] -‐ Burke B. RESTful Java with JAX-RS. O’Reilly Media, Inc., Nov 2009

28

10-‐07-‐2012


10 Appendix A – Opdrachtomschrijving

Over Data Archiving and Networked Services (DANS) DANS bevordert duurzame toegang tot digitale onderzoeksgegevens. Hiertoe stimuleert DANS dat wetenschappelijke onderzoekers gegevens duurzaam archiveren en hergebruiken, bijvoorbeeld via het online archiveringssysteem EASY. Tevens biedt DANS met NARCIS toegang tot duizenden wetenschappelijke datasets, e-‐publicaties en andere onderzoeksinformatie in Nederland. Daarnaast verzorgt het instituut training en advies en doet het onderzoek naar duurzame toegang tot digitale informatie. Gedreven door data zorgt DANS er met zijn dienstverlening en deelname in (inter)nationale projecten en netwerken voor dat de toegang tot digitale onderzoeksgegevens verder verbetert. DANS is een instituut van de Koninklijke Nederlandse Akademie van Wetenschappen (KNAW) en de Nederlandse Organisatie voor Wetenschappelijk Onderzoek (NWO). Introductie Om uitwisseling van onderzoeksdata tussen onderzoekers te vergemakkelijken, en om hen de gelegenheid te bieden hun data op een veilige en toekomst-‐ bestendige manier op te bergen, heeft DANS het Electronic Archiving System (EASY) ontwikkeld. Dit systeem is sinds februari 2007 online en wordt voortdurend verbeterd door het DANS ontwikkelteam. Veel wetenschappelijke disciplines gebruiken databases om grote hoeveelheden gegevens te structureren en doorzoekbaar te maken. Veelal hebben deze databases ook buiten de scope van het eigen onderzoeksproject een zekere toegevoegde waarde. Echter, slechts weinig onderzoekers zijn op de hoogte van de rijkdom aan data die te krijgen is bij andere onderzoekers. Bovendien wordt het delen van data, onder meer vanwege alle administratieve werkzaamheden eromheen, door onderzoekers eerder als een hindernis dan als een voorrecht ervaren. Het EASY systeem is bedoeld om het voor onderzoekers zo makkelijk mogelijk te maken hun data te delen met anderen en inzicht te krijgen in wat het datalandschap te bieden heeft. In het huidige EASY is het voor een gebruiker dus mogelijk om zijn data gemakkelijk op te slaan en te delen. Om het hergebruik van data verder te stimuleren wil DANS dat deze data ook gemakkelijk beschikbaar wordt voor externe applicaties. Om dit te bereiken zal een publieke API voor EASY moeten worden ontworpen en ontwikkeld. Opdracht In het kort kan de opdracht als volgt worden beschreven: “Ontwerp en implementeer een publieke API voor het DANS archief en demonstreer de mogelijkheden hiervan met een mobiele app.”

29

10-‐07-‐2012


De opdracht zal het volgende omvatten: 1. Schrijven van een plan van aanpak voor de uitvoering van de opdracht. 2. Analyseren van de bestaande software en mogelijkheden hiervan. 3. Ontwerpen van een publieke API (RESTful web serivce) volgens de vastgestelde requirements. 4. Implementeren van de publieke API volgens vastgestelde requirements. 5. Testen van de functionaliteit van de geïmplementeerde software volgens vastgestelde requirements. 6. Documenteren van de API waardoor toekomstige ontwikkelaars op basis van deze software verder kunnen werken. 7. Demonstreren van de mogelijkheden van de publieke API door middel van het ontwikkelen van een mobiele app voor het Android en/of iOS platform volgens vastgestelde requirements. Contact Meer informatie over deze opdracht kan worden verkregen via: Jan van Mansum Coördinator ICT / Supervisor Technische Infrastructuur Telefoon: +31(0)6 232 97 452 E-‐mail: [email protected]

30

10-‐07-‐2012


11 Appendix B – Plan van aanpak

Inhoudsopgave Voorwoord Samenvatting 1. Introductie 2. Projectopdracht 3. Aanpak en tijdsplanning 4. Projectinrichting 5. Kwaliteitsborging Bijlagen Voorwoord In dit document wordt er een zo goed mogelijk beeld geschetst over hoe en wanneer de opdracht uitgevoerd gaat worden. De functionaliteiten van de implementatie worden in samenwerking van zowel de opdrachtgever (DANS) alsmede de projectgroep bepaald. Dit document zal in grote lijnen het door ons te volgen proces beschrijven. Samenvatting DANS bevordert duurzame toegang tot digitale onderzoeksgegevens. Dit gebeurt onder andere met het digitale data archief genaamd EASY. Het probleem is dat EASY onderliggend een afgeschermde repository heeft dat alleen toegankelijk is door de EASY webservice. Het is dus nu voor derden niet mogelijk om applicaties of services te ontwikkelen die gebruik maken van de data in die repository. De opdracht bestaat uit het opzetten van een systeem om de repository publiekelijk toegankelijk te maken. Hiertoe zal een RESTful webservice bovenop EASY worden geimplementeerd. Tevens zal een demonstratie worden ontwikkeld in de vorm van een mobiele app. Het project is ingedeeld in de volgende stappen: vooronderzoek, ontwerp, implementatie/testen, documenteren, presenteren. We zullen ons verdiepen in de huidige werking van EASY, in REST principes en in het ontwikkelen van mobiele apps. Aan de hand van vastgestelde criteria zullen we evalueren welke bestaande software wij kunnen gebruiken om dit project te realiseren. Verder zullen we de implementatie test-‐driven uitvoeren op een agile manier, met wekelijkse iteraties en twee wekelijkse tussenrapportages.

31

10-‐07-‐2012


11.1 Introductie Data Archiving and Networked Services (DANS) is een instituut van de KNAW en NWO. DANS bevordert duurzame toegang tot digitale onderzoeksgegevens. Hiertoe zijn verschillende projecten uitgevoerd om digitale informatie persistent te preserveren. Een voorbeeld van een dergelijke oplossing is het Electronic Archiving SYstem (EASY). EASY maakt het voor wetenschappers mogelijk om hun onderzoeksdata te deponeren ofwel data van anderen te hergebruiken. Een motto van DANS luidt “open als het kan, beschermd als het moet”. Hiermee wordt bedoeld dat de data zo min mogelijk restricties moet hebben en zo mogelijk, toegankelijk is voor iedereen. Het huidige ontwerp van EASY is zodanig dat alle (meta)data opgeslagen wordt in een afgeschermde repository. Deze repository is op dit moment alleen toegankelijk vanuit de EASY webapplicatie. Hieruit volgt de aanleiding voor de totstandkoming van onze opdracht. Namelijk de wens om de repository publiekelijk toegankelijk te maken voor applicaties of services van derden. Dit document zal het kader schetsen waarin de opdracht zal worden uitgevoerd. We zullen ingaan op de huidige opbouw van EASY en de aanpassingen die wij zullen doorvoeren. Tevens zullen wij een afweging maken tussen reeds bestaande technologieën die bruikbaar zijn om de opdracht uit te voeren.

Figuur 9: EASY (https://easy.dans.knaw.nl)

32

10-‐07-‐2012


11.2 Projectopdracht In het kort kan de opdracht als volgt worden beschreven: “Ontwerp en implementeer een publieke API voor het DANS archief en demonstreer de mogelijkheden hiervan met een mobiele app.” De opdracht bevat de volgende globale elementen: 1. Schrijven van een plan van aanpak voor de uitvoering van de opdracht. 2. Analyseren van de bestaande software en mogelijkheden hiervan. 3. Ontwerpen van een publieke API (RESTful webservice) volgens de vastgestelde requirements. 4. Implementeren van de publieke API volgens de vastgestelde requirements. 5. Testen van de functionaliteit van de geïmplementeerde software volgens vastgestelde requirements. 6. Documenteren van de API waardoor toekomstige ontwikkelaars op basis van deze software verder kunnen werken. 7. Demonstreren van de mogelijkheden van de publieke API door middel van het ontwikkelen van een mobiele app voor het Android en/of iOS platform. De nadruk van het project ligt op het ontwerpen/implementeren/testen van de op REST principes gebaseerde webservice. Om dit te bewerkstelligen zullen wij een module moeten toevoegen aan het huidige systeem. Het huidige technisch ontwerp van EASY is weergeven in het volgende figuur. Het volledige technisch ontwerp is te vinden in bijlage A.

33

10-‐07-‐2012


Figuur 10: Deel van het technisch ontwerp van EASY.

Bovenstaand figuur toont dat EASY op een gemoduleerde wijze is opgezet. De business laag bijvoorbeeld, is strikt gescheiden van de interface (UI) laag. Deze structuur maakt het voor ons toegankelijker om een uitbreiding op het systeem te ontwikkelen. Om de gewenste verandering in het technische ontwerp te bewerkstelligen zullen wij een nieuwe laag toevoegen, namelijk de REST laag. Deze laag zal de RESTful service bevatten en deze zal communiceren met de ‘business’ laag alsmede met het ‘domain’. De voorgestelde verandering is gevisualiseerd in onderstaand figuur.

34

10-‐07-‐2012


Figuur 11: Voorgesteld technisch ontwerp

Ons voorstel omtrent de publieke API is dus om een nieuwe laag toe te voegen aan het systeem. Deze laag, de REST laag genaamd, bevat de RESTful API module. Deze module maakt gebruik van de ‘services’ module uit de business laag en de ‘domain’ module om zijn taak te kunnen vervullen. Voor het demonstreren van de werking van de RESTful API zal er een Android app ontwikkeld worden die gebruik maakt van de API. We hebben gekozen voor Android omdat deze geprogrammeerd wordt in Java. Dit leek ons praktisch aangezien EASY in Java is geschreven. De API zal dus ook in Java geschreven moeten worden. Tevens is het zo dat wij al ruime ervaring hebben met Java.

11.3 Aanpak en tijdsplanning In eerste instantie zullen wij ons gaan verdiepen in de huidige werking van EASY en de data die in de repository zit. Vervolgens zullen wij een vooronderzoek doen, onder andere omtrent het REST principe, bestaande bruikbare technologiën, integratie van de API in het systeem etc. Als het vooronderzoek is afgerond zullen we overgaan op het ontwerp van de API. We zullen met behulp van UML diagrammen visualiseren hoe het systeem concreet opgezet zal worden. Als ons ontwerp goed is gekeurd door de opdrachtgever gaan wij over op de implementatie van het systeem. De implementatie fase zullen wij test-‐ driven op een agile manier uitvoeren. Het testen en ontwikkelen van het systeem zal dus gefaseerd hand in hand gaan. Parallel aan het ontwerpen en ontwikkelen van de API zullen we dezelfde stappen doorlopen voor de Android app, alleen zal

35

10-‐07-‐2012


deze met een kleine vertraging plaatsvinden aangezien de app sterk afhankelijk is van de werking van de API. De tijdsplanning is als volgt: • • • • •

Vooronderzoek: 1 tot 2 weken Ontwerp: 1 week Implementatie/testen: 4 weken Documenteren: 1 week Verslag/presentatie: 2 weken

Als blijkt dat wij nog tijd overhebben dan willen we die besteden om nog een demonstratie te ontwikkelen van de REST API in de vorm van een widget voor een online portaal. Dit was een wens van onze begeleider bij DANS.

11.4 Projectinrichting Gedurende het vooronderzoek is het van belang dat wij ons inlezen in het principe van op REST gebaseerde architectuur. Als leidraad zullen wij de originele dissertatie van R.T. Fielding gebruiken. Fielding is de grondlegger van het REST principe [1]. Aangezien de dissertatie nog veel open laat betreffende specifieke server inrichting gebruiken we tevens het boek RESTful Web services [2]. Dit boek behandelt een goede variant van een REST architectuur, namelijk de Resource Oriented Architecture (ROA). Ons plan is om de implementatie volgens deze richtlijnen uit te voeren. We zullen ons gedurende het vooronderzoek moeten verdiepen in bestaande frameworks en software die het opzetten van een RESTful service vergemakkelijken. Wij zullen aan de hand van een aantal criteria een afweging maken over welke software het meest geschikt is voor ons project. De criteria die wij belangrijk achten zijn: • • • • • • • • •

Performance Heldere interface (zowel server als client) Goede documentatie Open-‐source Testbaarheid Ondersteuning https Faciliteit authenticatie Integratie met EASY JAX-‐RS ondersteuning [3] [4]

Na het kiezen van de bruikbare bestaande software zullen wij overgaan op het daadwerkelijke ontwerp van, in eerste instantie, de RESTful service. Hiertoe zullen wij de requirements analyseren en UML diagrammen maken. Deze diagrammen zullen we voorleggen aan de begeleiders ter goedkeuring. Na het ontwerp van de RESTful service gedaan te hebben zullen we het ontwerp voor de Android app maken op dezelfde manier.

36

10-‐07-‐2012


We hebben gekozen om de implementatie test-‐driven uit te voeren op een agile manier. Dit houdt dus in dat we zo veel mogelijk geautomatiseerde tests zullen maken en dat we iteratief te werk zullen gaan. Aangezien we beperkte tijd hebben voor het project is besloten om iteraties een duur te geven van één week. Wij denken dat we met dergelijke iteraties efficient te werk kunnen gaan en tijdig kunnen bijsturen in de uitvoering van het project. Iedere twee iteraties (dus om de twee weken) zullen we een rapport opsturen naar onze begeleiders. Naast de unit en integratie tests die wij zullen ontwikkelen willen wij ook stress-‐ tests uitvoeren op de uiteindelijke server. Dit willen we doen om de performance en stabiliteit van de implementatie te testen. Achteraf zullen we de documentatie bundelen en verhelderen. De keuzes die gemaakt zijn tijdens de ontwerp en implementatie fasen worden hierin toegelicht. De documentatie zal tevens dienen als een programmeurs handleiding voor toekomstige ontwikkelaars.Tevens zullen we een presentatie opstellen over het project. De presentatie zal zowel bij DANS als op de TU Delft gegeven worden.

11.5 Kwaliteitswaarborging De kwaliteit van het uiteindelijke product zal worden gewaarborgd door de geautomatiseerde test suites. De begeleiders (en overige stakeholders) kunnen gedurende het project bijsturen door middel van feedback op onze twee wekelijkse rapportages of door reactie op het resultaat van elke iteratie.

37

10-‐07-‐2012


11.6 (PvA) Bijlage A – Technische architectuur EASY

38

10-‐07-‐2012


12 Appendix C – Oriëntatieverslag

12.1 Inleiding Dit document is een verslag van het vooronderzoek dat wij hebben gedaan naar de huidige werking van EASY en naar de gewenste architectuur van de API die wij moeten ontwikkelen. In eerste instantie zullen wij EASY onder de loep nemen. Daarna zullen we het REST principe uiteenzetten om vervolgens over te gaan op de daaruit voortvloeiende ROA architectuur. We zullen tevens bekijken welke REST frameworks er reeds bestaan en een afweging maken tussen de populairste met de criteria die genoemd zijn in het plan van aanpak. Verder zullen we onderzoeken of er overige frameworks zijn die voor ons het werk kunnen verlichten in de implementatie fase. Ten slotte zullen we kijken naar het Android platform en de implicaties die het systeem heeft op de implementatie van de client app die dient ter demonstratie van de API. Concluderend zullen we alle keuzes samenvatten die voort zijn gevloeid uit ons vooronderzoek.

12.2 EASY

Het Electronic Archiving SYstem (EASY) is ontwikkeld door DANS om onderzoekers in staat te stellen hun onderzoeksdata digitaal te preserveren en om hergebruik mogelijk te maken. We zullen een toelichting geven van de software die door EASY gebruikt wordt. Vervolgens zullen we ingaan op de werking van EASY. EASY maakt gebruik van een Fedora Commons32 repository (niet te verwarren met het besturingsysteem) in combinatie met een PostgreSQL33 database om de (meta)data op te slaan. Voor de userbase wordt gebruik gemaakt van het OpenLDAP framework34. Hierin zijn alle gebruikers van EASY opgeslagen. Tevens maakt EASY gebruik van Apache Solr35. Dit is een op Lucene gebaseerde zoek-‐server die gebruikt wordt om efficient door de data te zoeken. Voor de front-‐end is er een webapplicatie ontwikkeld op basis van Apache Wicket36. EASY maakt het voor externe applicaties ook mogelijk om metadata te harvesten. Dit wordt gedaan door middel van het Proai37 framework. Er is dus kennelijk wel enige vorm van machine-‐machine interactie geimplementeerd in EASY (in tegenstelling tot wat wij dachten bij het schrijven van het plan van aanpak) maar dit is niet op een RESTful manier opgezet en maakt alleen de open metadata beschikbaar. 32 http://fedora-‐commons.org/ 33 http://www.postgresql.org/ 34 http://www.openldap.org/ 35 http://lucene.apache.org/solr/ 36 http://wicket.apache.org/ 37 http://proai.sourceforge.net/

39

10-‐07-‐2012


De globale architectuur van EASY is op te delen in drie lagen (three-‐tier architecture38). Het systeem bestaat uit een data laag, een logica laag en een presentatie laag. De verantwoordelijkheden van de lagen zijn strikt gescheiden. De lagen zijn derhalve vervangbaar door nieuwere implementaties zonder consequenties voor de overige lagen. Dit type architectuur zorgt voor een overzichtelijkere indeling van de code. De ‘three-‐tier’ architectuur van EASY is in onderstaand figuur gevisualiseerd.

Figuur 12: Three-tier architecture EASY

De presentatie laag bestaat op dit moment uit een webapplicatie bedoeld voor eindgebruikers. Het doel van onze opdracht is om een presentatie laag te ontwikkelen voor machines, om derhalve machine-‐machine interactie mogelijk te maken. Dit houdt dus in dat we een extra presentatie laag maken die zal communiceren met de ‘business’ laag. De business laag bevat alle routines en methoden die wij nodig hebben om data op te vragen uit EASY. Tevens bevat het de middelen om data toe te voegen of aan te passen. Gebruikers van EASY kunnen datasets aanmaken in het systeem. Afhankelijk van het type data dat de onderzoeker wil deponeren wordt een metadata formaat gekozen en ingevuld. Als de onderzoeker bijvoorbeeld archeologische data wil deponeren dan moet hij/zij archeologische metadata invullen. De metadata wordt gebruikt om de dataset te classificeren en de inhoud te beschrijven. Aangezien de daadwerkelijke data in willekeurige bestandsformaten kan worden aangeleverd is het voor EASY ondoenlijk om zoekopdrachten aan de hand van de 38 http://en.wikipedia.org/wiki/Multitier_architecture

40

10-‐07-‐2012


data uit te voeren. Vandaar dat EASY de metadata gebruikt om zoekopdrachten uit te voeren. De metadata wordt in EASY opgeslagen in een gestandardiseerd XML formaat genaamd Dublin Core (DC)39. De metadata die EASY opslaat bevat zowel DC metadata als EASY specifieke metadata, dit is metadata die EASY gebruikt om interne administratie bij te houden. Op het moment van schrijven ondersteunt EASY alleen het archeologische metadata formaat en het generieke formaat voor sociale wetenschappen. EASY is echter zo opgebouwd dat nieuwe formaten zeer gemakkelijk toegevoegd kunnen worden. Hier zullen we dan ook rekening mee moeten houden bij de implementatie van de RESTful service. EASY kent verschillende soorten gebruikers: • Anonymous: niet-‐ingelogde gebruiker • Known: wel-‐ingelogde gebruiker. Bijv. om aanvraag ('permission request') voor een dataset te kunnen doen. Known users kunnen mogelijk meer bestanden bekijken/downloaden van sommige datasets. Een subcategorie hiervan zijn de z.g. depositors, gebruikers die een dataset deponeren (of gedeponeerd hebben). Kenmerkend is dat zij een speciale relatie met een dataset hebben (zij zijn de maker ervan). • Archivist: Groep van gebruikers die binnengekomen datasets kan verwerken en beheren. Per dataset en per bestand in een dataset kunnen verschillende rechten aan de verschillende soorten gebruikers toegekend worden. De belangrijkste daarvan zijn de visibility en accessibility die per bestand ingesteld kunnen worden op: • Anonymous • Known • Restricted request (gebruiker moet toestemming vragen aan depositor) • Restricted group (de administrator moet groepsrechten toekennen aan de gebruiker) • None (bestanden zijn niet toegankelijk vanuit EASY) Een dataset in EASY kan in een aantal verschillende staten verkeren. Hieronder is de transitiediagram weergeven van een dataset in EASY.

39 http://dublincore.org/

41

10-‐07-‐2012


Figuur 13: Transitie diagram van een dataset

Een dataset is in ‘draft’ state als hij opgeslagen wordt. Dit houdt in dat de onderzoeker enige metadata heeft ingevuld en wellicht wat data heeft geupload maar de dataset nog niet volledig heeft gesubmit. Als de dataset gesubmit wordt dan verandert zijn state naar ‘submitted’. Vanaf dat moment kan de onderzoeker niks veranderen aan zijn dataset, alleen bekijken. Een archivaris krijgt de submitted dataset te zien, hij controleert deze en past hem zo nodig aan. De archivaris kan bij gebrekkige of incorrecte data de dataset terug naar ‘draft’ state zetten zodat de onderzoeker wijzigingen kan doorvoeren. Als de dataset goed is gekeurd door een archivaris, kan de dataset gepubliceerd worden. Gepubliceerde datasets kunnen door niemand gewijzigd worden. Normale gebruikers in EASY kunnen alleen gepubliceerde datasets zien. Achteraf kan een dataset nog in de ‘maintenance’ state worden gezet zodat enkele wijzigingen kunnen worden doorgevoerd. Ook kan een dataset verwijderd worden, zijn state gaat dan naar ‘deleted’. De dataset is dan nog wel aanwezig in het systeem, pas als er een ‘purge’ wordt uitgevoerd is de dataset echt uit de repository verwijderd. Het is de bedoeling dat onze RESTful webservice de rechten en restricties van datasets strikt naleeft, archivarissen moeten alle datasets kunnen bekijken en afhankelijk van de staat tevens kunnen aanpassen. Normale gebruikers moeten alleen gepubliceerde datasets kunnen bekijken en downloaden. Datasets die gebruikers zelf hebben gedeponeerd moeten ze altijd kunnen bekijken maar alleen in ‘draft’ state kunnen ze wijzigingen doorvoeren. Het volledige keuzemodel voor de gebruikersrechten met betrekking tot datasets en bestanden is weergeven in appendix A.

42

10-‐07-‐2012


12.3 REST In dit gedeelte zullen we een kort overzicht geven van het REST principe zoals voorgesteld in de dissertatie van R.T. Fielding [1]. Fielding stelt voor om de architectuur van een webservice te bekijken vanuit de behoeften van het systeem als geheel zonder constraints, om vervolgens geleidelijk constraints toe te voegen. De REST architectuur heeft bepaalde (verplichte) constraints die we in dit gedeelte zullen bespreken. De eerste constraint wordt de client-server constraint genoemd. Het betreft hier het bekende principe van een server die wacht op requests van clients om deze vervolgens af te handelen en een response terug te sturen. De belangrijkste gedachte achter deze constraint is de scheiding van zorgen (separation of concerns). Hiermee wordt bedoeld dat er een duidelijke scheiding moet bestaan tussen de zorgen van de client en de zorgen van de server. De client moet zijn eigen staat bijhouden en de server zijn eigen. Het mag dus bijvoorbeeld niet zo zijn dat de server een staat of informatie bijhoudt dat bij de client hoort. Hieruit vloeit de volgende constraint voort namelijk, stateless. Vanwege de scheiding van zorgen moet de communicatie tussen client en server stateless zijn. Het komt erop neer dat iedere request die door de client wordt gestuurd naar de server alle informatie moet bevatten die benodigd is om die request af te handelen. De afhandeling van een request door de server mag dus niet afhankelijk zijn van eerder uitgevoerde acties. Kort gezegd, er mag geen sessie voor de client bijgehouden worden op de server. De volgende constraint betreft de cache. De cache constraint houdt in dat de data in een response impliciet of expliciet gelabeled moet zijn als cacheable of non-‐cacheable. Als een response cacheable is dan kan de client deze opslaan voor hergebruik. Dit bevordert efficientie en vermindert druk op de server. De centrale eigenschap die de REST architectuur onderscheidt van andere netwerk-‐architecturen is de uniform interface. Het gaat hier om een uniforme en gestandaardiseerde manier van communicatie tussen de client en server. Deze moet op dergelijke manier zijn opgezet dat de onderliggende implementaties losgekoppeld en vervangen kunnen worden zonder effect op de werking van het geheel. Een dergelijke uniforme manier van communicatie versimpeld de totale architectuur en koppelt de implementatie los van de services die worden aangeboden. Een nadeel is wel dat deze constraint de efficientie verlaagt omdat informatie wordt verzonden op een gestandaardiseerde manier en niet op een manier die specifiek is voor de behoeften van de applicatie. Om de architectuur verder te verbeteren is de layered system constraint toegevoegd. Deze constraint schrijft voor dat systemen hierarchisch gelaagd opgezet moeten worden (zoals in EASY het geval is). Elk component kan niet verder “zien” dan de intermediare laag waarmee het communiceert. Door op

43

10-‐07-‐2012


dergelijke manier de kennis van componenten te beperken vermindert de totale systeem complexiteit en wordt onafhankelijkheid bevordert. De laatste (en enige optionele) constraint in het REST principe is de code-on- demand constraint. REST staat het toe om functionaliteit uit te breiden door het downloaden en uitvoeren van code in de vorm van applets of scripts. Dit maakt de client applicaties simpeler door het aantal functionaliteiten die pre-‐ ontwikkeld moeten worden te verminderen. Tevens zorgt het toestaan van downloaden van nieuwe functionaliteiten voor een uitbreidbaar systeem. Daarentegen vermindert het ook de zichtbaarheid van het systeem (bijvoorbeeld doordat de code niet uitvoerbaar is op ieder platform). Om die reden is deze constraint optioneel. De bovengenoemde constraints definieren het REST principe. De beschrijving laat echter veel open wat betreft daadwerkelijke implementatie. Waar wel over wordt uitgeweid is het principe van resources en representaties. Een resource is in principe elk stukje informatie dat door de server als zodanig naar de client kan worden gecommuniceerd. Een resource heeft altijd een unieke identifier (bijv. URL of URN) zodat de client daarnaar kan refereren. Als een client een bepaalde resource opvraagt van de server dan hoeft hetgeen de server terugstuurt niet in hetzelfde formaat te zijn als de daadwerkelijke resource. De server stuurt dan een representatie terug van de resource (dit kan bijvoorbeeld een HTML document zijn of een JPEG plaatje). De server bevat tevens opvraagbare metadata van de resources en de representaties (bijvoorbeeld media type, last-‐ modified time). Tevens is er voor elke resource zogenoemde ‘control data’ aanwezig op de server (bijvoorbeeld if-‐modified-‐since, cache-‐control). Het uiteindelijke doel van het REST principe is om de resources zo uniform en helder mogelijk beschikbaar te maken voor de ‘buitenwereld’. Dergelijke architectuur vereist dat de architect denkt in termen van resources in plaats van in termen van functies. Voor hetgeen wij moeten ontwikkelen is dit bij uitstek de geschikte manier van denken aangezien wij de resources die in EASY zitten beschikbaar moeten maken voor applicaties van derden.

44

10-‐07-‐2012


12.4 ROA Zoals eerder genoemd laat de dissertatie van R.T. Fielding veel open wat betreft implementatie en details van een REST architectuur. Het boek RESTful Web Services [2] probeert deze gaten enigzins op te vullen en stelt derhalve een architectuur voor die de Resource Oriented Architecture (ROA) wordt genoemd. In dit gedeelte zullen we de ROA architectuur toelichten en motiveren waarom we hebben gekozen voor een dergelijk uitgangspunt voor ons project. Er zijn vier aspecten waarop ROA een toevoeging of uitbreiding voorstelt op het REST principe. Het betreft hier de volgende vier hoofdpunten: • Addressability • Statelessness • Connectedness • Uniform interface De addressability refereert naar de adresseerbaarheid van de resources. Een applicatie is adresseerbaar als alle interessante informatie op de server door middel van een URI kan worden opgevraagd. Elke resource moet dus blootgesteld worden aan de buitenwereld door middel van een URI. Over het algemeen betreft het hier vaak een oneidige verzameling van URI’s. Vanuit de eindgebruiker geredeneerd is de adresseerbaarheid het belangrijkste aspect van een website of webservice. Zonder adresseerbaarheid zou de eindgebruiker vanzelfsprekend niet (of moeilijk) kunnen refereren naar de resources. Met adresseerbaarheid wordt tevens gesuggereerd dat het een persistente manier van adressering moet zijn. De URI moet dus (voor zover dat mogelijk is) duurzaam zijn. Het aspect van statelessness is al genoemd in de uitleg over REST maar er wordt een andere manier van redeneren voorgesteld in het boek. Statelessness als beschreven in de dissertatie betekent dat elke request op de server in complete isolatie moet gebeuren. De server is nooit afhankelijk van informatie uit vorige requests. De ROA architectuur schrijft voor dat statelessness beschouwd moet worden in termen van adresseerbaarheid. Statelessness zegt dat de mogelijke staten van de server tevens resources zijn. Daarom zouden deze staten allemaal een eigen URI moeten krijgen en als zodanig addresseerbaar moeten zijn. Een toegevoegd aspect is de notie van connectedness (verbondenheid). Soms zijn representaties van resources niets meer dan geserializeerde data structuren. Echter komt het vaak voor in RESTful services dat representaties eigenlijk hypermedia zijn. Met hypermedia wordt bedoeld dat representaties niet slechts data bevatten maar tevens links naar andere resources. De resources zijn verbonden met elkaar, vandaar de term connectedness. Het idee is dat de service in verschillende staten gezet kan worden door simpelweg de links te volgen in de representaties. Het web (www) is het grootste voorbeeld van een RESTful architectuur en de connectedness van het web geeft het de enorme potentie en kracht die we allemaal kennen.

45

10-‐07-‐2012


Het laatste aspect is de uniform interface. Dit aspect is reeds besproken in de dissertatie maar daar wordt niet gesproken welke specifieke interface gebruikt zou moeten worden. ROA stelt voor om het http protocol te gebruiken zoals het ooit bedoeld was. Elk http request heeft los van de headers en de data een bepaalde methode warmee het geassocieerd wordt. In het hedendaags internet zijn slechts twee van deze http-‐methoden grootschalig in gebruik. Dat zijn de GET en POST methoden. Browsers ondersteunen zelfs geen andere http-‐ methoden. Het idee is eigenlijk om deze methoden niet langer te misbruiken om alles te doen maar de methoden alleen daar te gebruiken waar toepasselijk. Om een voorbeeld te noemen: een GET moet gebruikt worden om een representatie van een resource op te vragen en niet om bijvoorbeeld een resource aan te passen. De ROA architectuur stelt dus in principe dat de HTTP methoden gebruikt moeten worden zoals ooit de intentie was van de bedenkers. Het volgende tabel toont de meest gangbare http methoden en de acties die ermee gepaard kunnen gaan. HTTP methode Beschrijving GET Verkrijg een resource PUT Insert of update een resource DELETE Verwijder een resource POST Insert een nieuwe resource met relatie tot een gegeven andere resource HEAD Controleert het bestaan van een resource (GET zonder body) OPTIONS Retourneert de HTTP methoden die op een gegeven resource van toepassing zijn Tabel 1: Toelichting HTTP methodes

Bovenstaand tabel is duidelijk wat betreft de acties die volgen uit de verschillende HTTP methoden. Wellicht verdient de POST methode enige toelichting. Om een nieuwe resource aan te maken wordt gewoonlijk de PUT methode gebruikt. De request bevat dan alle informatie om de nieuwe resource aan te maken. Vaak is het echter zo dat resources moeten worden aangemaakt met relatie tot andere resources. Het kan bijvoorbeeld voorkomen dat een nieuwe resource een ‘parent-‐child’ relatie vormt met een reeds bestaande resource. De nieuwe resource moet dus een kind worden van de bestaande resource. In dit geval wordt de POST methode gebruikt in plaats van de PUT. De request bevat alle informatie die nodig is om de nieuwe resource aan te maken maar bevat tevens een referentie naar de oude resource die als parent zal dienen van de nieuwe resource. Het komt er dus op neer dat POST wordt gebruikt om nieuwe resources in relatie tot anderen aan te maken. De ROA is een RESTful architectuur die de constraints van REST verder aanscherpt en concreter definieert. De concretere constraints zijn voor ons de reden dat wij kiezen voor een ROA architectuur voor de REST laag die we op EASY gaan implementeren. Aspecten als addressability en connectedness voegen daar zeer praktische manieren van communicatie aan toe. We zullen voor het ontwerp en de implementatie van de ROA de stappen volgen die worden voorgesteld in het boek.

46

10-‐07-‐2012


12.5 RESTful frameworks In dit gedeelte bekijken we een aantal frameworks die ons kunnen helpen bij het maken van een RESTful Web Service. Een belangrijk criterium is de ondersteuning van JAX-RS [3][4]. JAX-RS is een specificatie gebaseerd op een java API voor RESTful Web Services. Deze specificatie is door Sun40 opgesteld. Elk op een JAX-RS gebaseerde API zal RESTful zijn. Het gebruik van annotaties staat centraal bij JAX-RS. Deze annotaties worden onder andere gemapt naar HTTPrequestmethoden. De annotatie @GET bijvoorbeeld mapt naar de HTTPrequestmethode GET. Een andere noemenswaardige annotatie is @PATH. Het gebruik van @PATH zorgt ervoor dat een resource aan een bepaalde URI wordt toegekend. Het gevolg van ondersteuning van JAX-RS is relatief makkelijk interpreteerbare code. De frameworks die wij evalueren zijn geheel op de JAX-RS specificatie gebaseerd. De resterende criteria voor evaluatie zijn: • • • • • • • •

Performance Heldere interface (zowel server als client) Goede documentatie Open-source Testbaarheid Ondersteuning https Faciliteit authenticatie Integratie met EASY

Onder het criterium integratie met EASY wordt onder andere verstaan ondersteuning van Maven en een in Java geschreven framework. Elke framework die door ons is geëvalueerd voldoet aan de bovengenoemde eisen. De volgende vier frameworks zijn opgenomen in onze beoordeling: • • • •

Apache Wink41 Project Jersey42 JBoss RestEasy43 The Restlet framework44

Apache Wink is een op de JAX-RS specificatie gebaseerde framework. Deze biedt evenals de overige drie bovengenoemde frameworks een manier om op een RESTful manier een webservice te ontwikkelen. Elke van de bovengenoemde frameworks is tevens open-source. De Apache Wink framework heeft voor zowel de client als de server een interface. De server module wordt gebruikt voor het ontwikkelen van RESTful Web services. De client module maakt het daarentegen mogelijk om met RESTful Web services te communiceren. In het onderstaande figuur wordt de interactie weergeven tussen een client en een server met behulp van Apache Wink. De client stuurt een HTTP request naar de “Apache Wink REST Servlet”. Vervolgens 40 http://www.oracle.com/us/sun/index.htm 41 http://incubator.apache.org/wink/ 42 https://wikis.oracle.com/display/Jersey/Main 43 http://www.jboss.org/resteasy 44 http://www.restlet.org/

47

10-‐07-‐2012


gebruikt de servlet de “Request Processor” in combinatie met de request URI om te bepalen welke resource methode aangeroepen moet worden.

Figuur 14: Werking van een web service met Apache Wink

Apache Wink biedt de mogelijkheid om een gebruikersnaam en wachtwoord te encoderen volgens de HTTP basic authentication methode. Het testen van client en server communicatie gaat via het mocken van responses en requests bij Apache Wink. Tenslotte, de Apache Wink framework is onderdeel van het Apache Incubator project45. Dit betekent voor ons dat er enige onzekerheid heerst over de toekomst van de betreffende framework. Project Jersey is een reference implementation van de JAX-RS specificatie ontwikkeld door Sun. Deze framework heeft evenals Apache Wink een module voor zowel de server als de client. Bovenop de basic authentication voor encodering van gebruikersnaam en wachtwoord, biedt Project Jersey de mogelijkheid om gebruik te maken van Digest access authentication (een complexere authenticatie methode). Het is tevens mogelijk om via een HTTPS protocol requests te verzenden naar een server. In tegenstelling tot Apache Wink kunnen er niet via de framework requests en responses gemockt worden, er is echter wel een test framework opgesteld (speciaal voor Project Jersey). Dit framework kan gebruik maken van embedded containers (intern gedefinieerde servers) om de communicatie tussen de client en de server te testen. De embedded containers van dit framework vergemakkelijken het schrijven van unit en integratie tests.

45 http://incubator.apache.org/projects/wink.html

48

10-‐07-‐2012


JBoss RestEasy is in opdracht van Red Hat46 gemaakt. Deze framework onderscheidt zich op de volgende vlakken van de bovenstaande frameworks: de communicatie tussen de client en de server kan op twee manieren worden getest. De eerste manier is het mocken van requests en responses. Een andere manier is om gebruik te maken van embedded containers (de Sun JDK HTTP Server of de TJWS embeddable Servlet Container). De authenticatie die de framework faciliteert zit nog in de experimentele fase en kan nog niet worden beschouwd als productiewaardig. Elk van de drie bovenstaande frameworks zijn geïmplementeerd nadat de JAX-RS specificatie was opgesteld. The Restlet framework daarentegen was al voordat de JAX-RS specificatie bekend was geïmplementeerd (deze implementatie is echter nog niet volledig). De framework kan onderverdeeld worden in drie modules: Restlet API, The Noelios Restlet Engine(NRE) en Optional Restlet extension. In het laatst genoemde onderdeel worden de JAX-RS specificatie geïmplementeerd. Als gevolg hiervan is het mogelijk voor een client om elk remote HTTP-based service te consumeren(en niet alleen JAX-RS services). De authenticatie-methodes die door de framework worden ondersteund zijn Basic en Digest access authentication. HTTPS wordt niet direct ondersteund door de framework, echter er bestaan connectors die HTTPS connectie mogelijk maken. Voor het meten van de perfomance van de vier frameworks wordt voor elke framework bepaald hoeveel REST-‐based GET requests (afgevuurd door middel van een test script) per seconde verwerkt kunnen worden (transactions per second). De test script werd voor de performance meting 1500 keer uitgevoerd [5]. Onderstaand figuur is een grafische weergave van de performance van de frameworks.

Figuur 15: Performance van de verschillende frameworks

46 http://www.redhat.com/

49

10-‐07-‐2012


In figuur 15 wordt duidelijk dat de Restlet Framework over het algemeen de minst goede framework is qua perfomance (voor de gebruikte test script). De drie andere frameworks daarentegen hebben ongeveer gelijke performance (met een lichte voorsprong voor Project Jersey bij Mean TPS en een voorsprong van Apache Wink bij Peak TPS). We hechten meer waarde aan de Mean TPS omdat deze de gemiddelde performance reflecteert. In Tabel 2 wordt voor elke framework ten opzichte van de criteria een gradatie toegekend met waardes van -‐-‐,-‐,+-‐,+,++. De waarde – correspondeert met het ontbreken van een criterium. Een ++ daarentegen betekent dat een criterium uitstekend wordt gefaciliteerd. Uit de tabel wordt duidelijk dat Project Jersey het meest geschikte framework is voor ons project. Per-‐ Inter-‐ Docu-‐ Open-‐ Test-‐ HT Aut-‐ Inte-‐ formance face mentatie source baarheid TP henticatie gratie S met EASY Apache + ++ ++ ++ + -‐-‐ + ++ Wink Project ++ ++ ++ ++ + ++ ++ ++ Jersey JBoss +-‐ ++ ++ ++ ++ -‐-‐ -‐ ++ RestEasy The -‐ ++ ++ ++ -‐ + ++ ++ Restlet frame work Tabel 2: Beoordeling RESTful frameworks

12.6 Overige frameworks

Aangezien we hebben besloten om de implementatie test-‐driven uit te voeren hebben we een goede manier nodig om de API te testen. We hebben een keuze moeten maken tussen twee frameworks namelijk, Jersey-‐Test-‐Framework47 en REST-‐assured48. Beide zijn java test frameworks, echter is de eerste specifiek ontwikkeld voor Jersey. Aangezien wij hebben besloten om Jersey te gebruiken zou dit goed uit kunnen komen met de aansluiting van de tests op de code. Echter hechten wij ook grote waarde aan de houdbaarheid van de geautomatiseerde tests die we zullen schrijven. Als er ooit besloten zal worden om Jersey te vervangen met een ander framework (dat tevens JAX-‐RS ondersteund) dan zouden de tests niet meer werken. Met REST-‐assured is dat probleem minder groot aangezien deze niet specifiek voor een bepaald framework is geschreven maar voor RESTful services in het algemeen. Een ander voordeel van het REST-‐assured framework is de hamcrest-‐achtige syntax. De test regels vertalen daardoor zeer natuurlijk naar de menselijke interpretatie. Hierdoor zullen de tests veel leesbaarder worden. We zullen om deze redenen 47 http://jersey.java.net/nonav/documentation/latest/test-‐framework.html 48 http://code.google.com/p/rest-‐assured/

50

10-‐07-‐2012


het REST-‐assured framework gebruiken om onze geautomatiseerde tests te ontwikkelen. Verder hebben we een framework nodig om java objecten om te zetten in XML en/of JSON structuren. Dit is nodig omdat de API de resources uit EASY haalt in de vorm van java object instanties maar daarna deze moet serializeren naar een vorm die met de response meegestuurd kan worden. De formaten XML en JSON zijn het populairst voor dergelijke doeleinden. Er bestaan ook veel verschillende frameworks voor java die instanties kunnen omzetten naar de genoemde formaten. Echter is het zo dat EASY reeds gebruik maakt van het JiBX49 framework. Om die reden zullen wij dezelfde lijn volgen en tevens JiBX gebruiken voor de API.

12.7 Android Wij hebben besloten om de client demonstratie van de API te implementeren in de vorm van een app voor het Android50 besturingssysteem. De redenering hierachter is dat EASY in java geschreven is, wat dus betekent dat we de RESTful API tevens in java zullen ontwikkelen. Om dan in dezelfde lijn te blijven wat betreft programmeertaal is Android eigenlijk de enige kandidaat die werkt met java. Door de implementatie in java te doen kunnen we gebruik maken van de meegeleverde client libraries van Jersey. Daar komt ook nog bij dat wij goed bekend zijn met java. Een bijkomend voordeel is dat Android een besturingssysteem is dat niet gelimiteerd is tot één enkele fabrikant van apparatuur. Android draait op telefoons en tablets van vele verschillende fabrikanten. Onze app zal dus op veel verschillende apparaten werken. Nog een noemenswaardig voordeel is dat er een Android plugin51 bestaat voor de eclipse52 IDE. Aangezien wij zeer bekend zijn met eclipse is het ook handig en tijdbesparend dat we ons project daarin kunnen implementeren. Bij de plugin zit tevens een Android emulator waarmee we de app kunnen testen tijdens het ontwikkelen.

12.8 Conclusie

Naar aanleiding van ons vooronderzoek hebben we gekozen om Project Jersey te gebruiken bij de implementatie van de (op REST/ROA principes gebaseerde) API. Voor de test framework is de keuze gevallen op REST-‐assured. Tevens is besloten om JiBX te utiliseren voor de serializatie van java objecten naar XML en/of JSON formaten. Als front-‐end demonstratie van de mogelijkheden van de API hebben we besloten om een app te ontwikkelen voor het Android besturingssysteem.

49 http://jibx.sourceforge.net/ 50 http://www.android.com/ 51 http://developer.android.com/sdk/eclipse-‐adt.html 52 http://www.eclipse.org/

51

10-‐07-‐2012


12.9 (OV) Appendix A -‐ Keuzemodel gebruikersrechten EASY

52

10-‐07-‐2012


13 Appendix D – Requirements Analysis Document – API

13.1 Introductie 13.1.1 Doel van het systeem Het doel van de API is het mogelijk maken van het ontwikkelen van applicaties/services die gebruik maken van de (meta)data die in de repository van EASY zit. Momenteel is het namelijk niet mogelijk voor derden om applicaties te ontwikkelen die gebruik maken van de informatie in EASY. De API zal het hergebruik van de onderzoeksdata ten goede komen. Tegelijkertijd zal de API men in staat stellen om meerwaarde te creëren met de (meta)data door het ontwikkelen van plugins, apps, webservices en mashups. 13.1.2 Scope van het systeem Het systeem moet derden in staat stellen om de resources (data en functies) in EASY te gebruiken in de eigen programmatuur. Gedurende dit project zullen we ons beperken tot de functies die normale gebruikers kunnen uitvoeren in EASY. We laten administrator en archivaris functies derhalve achterwege. Dit hebben we besloten vanwege de beperkte tijd die we hebben om dit project uit te voeren. 13.1.3 Doelen en succes-‐criteria van het project Het voornaamste doel van het project is het ontwikkelen van een uniforme manier van machine-‐machine communicatie met EASY. Belangrijk is dat we genoeg resources en functies aanbieden zodat ontwikkelaars van externe applicaties niet beperkt zullen zijn door de API. Het moet gemakkelijk zijn om te communiceren met EASY. Dit houdt in dat de API een heldere interface moet hebben en dat requests gemakkelijk vertaald kunnen worden naar hun menselijke interpretatie. Het komt er dus op neer dat we de criteria die geldt voor RESTful systemen en de Resource Oriented Architecture (ROA) hanteren. Tevens is belangrijk dat de performance van de API een niet te grote overhead levert bovenop de huidige performance van EASY. Als richtlijn willen we stellen dat communicatie via de REST API niet meer dan 20% overhead moet leveren bovenop de huidige performance. Deze extra 20% zal de API gebruiken om de request te interpreteren de correcte functies aan te roepen binnen EASY en om het resultaat om te zetten naar een vorm die als respons terug gestuurd kan worden naar de client. De performance richtlijn kunnen we handhaven/bewaken door geautomatiseerde tests te ontwikkelen die metingen verrichten aan de responstijden van de server. Het uiteindelijke doel is om een demonstrators te ontwikkelen die de mogelijkheden van de API demonstreren. We willen een app ontwikkelen voor het Android besturingssysteem en een plugin voor Drupal53. De demonstrators moeten de zowel de werking als de mogelijkheden van de API duidelijk naar voren brengen.

53 http://drupal.org/

53

10-‐07-‐2012


13.1.4 Overzicht We zullen in dit document een overzicht geven van het huidige systeem waarna we zullen uiteenzetten wat de aanpassingen zijn die wij voorstellen om de API te ontwikkelen. Verder zullen we de requirements specificeren en opdelen in functionele en non-‐functionele requirements. Tevens zullen we ingaan op het technisch ontwerp en de daarbij horende UML modellen.

13.2 Huidig systeem In het oriëntatieverslag zijn we uitgebreid ingegaan op de werking van EASY en de software die EASY gebruikt om de functionaliteit te vervullen. We zullen hier vanuit een ander perspectief de architectuur van EASY belichten. In figuur 16 is een diagram weergeven dat de afhankelijkheden van de verschillende modules toont waar EASY uit bestaat.

Figuur 16: Onderlinge afhankelijkheden van de EASY modules

Zoals te zien is in bovenstaand figuur is EASY opgebouwd in modules die strikt een eigen verantwoordelijkheid hebben. Iedere module kan dus worden losgekoppeld en vervangen door een andere implementatie zolang de interface maar gelijk blijft. Het is zelfs zo dat de modules die in Dans Commons zitten

54

10-‐07-‐2012


gebruikt worden door meerdere projecten. Deze modules zijn dus niet specifiek voor EASY. De front-‐end wordt verzorgd door de Web UI module. Deze gebruikt Dans Wicket om de daadwerkelijke websites te genereren. Om informatie op te vragen uit de overige modules maakt de Web UI gebruik van de Services module. Om de beveiliging te handhaven maakt de Web UI ook nog gebruik van de Security module. Deze twee modules (Services en Security) zijn cruciaal voor de implementatie van de REST API. Om deze reden hebben we een klassendiagram opgesteld die de interactie van de Services weergeeft met het domeinmodel. Dit dient ter inzicht van de dataflow en de interne interactie van het gedeelte van EASY dat wij gaan gebruiken voor de implementatie van de API.

Figuur 17: Klassendiagram Services interactie met Domain

13.3 Voorgesteld systeem

Het voorstel voor de implementatie van de REST API is reeds besproken in het plan van aanpak en in het oriëntatieverslag. We zullen in dit gedeelte verder gaan op het oorspronkelijke idee en het plan uitbreiden met requirements en UML diagrammen. 13.3.1 Overzicht De huidige opzet van EASY maakt het voor ons makkelijker om de REST API te implementeren. Het komt er op neer dat we een additionele module zullen toevoegen (EASY-REST) die net als de Web UI de Services gebruikt om informatie uit EASY op te halen en/of te manipuleren mits de Security de authorisatie goedkeurt. De web interface wordt opgebouwd met behulp van de Dans Wicket module. Aangezien onze REST module geen web interface moet opbouwen maar een HTTP respons moet genereren zal deze geen gebruik maken van Dans Wicket. Echter zal wel een afhankelijkheid worden toegevoegd naar Project

55

10-‐07-‐2012


Jersey. Deze zal de mapping van URI’s naar resources en representaties verzorgen. 13.3.2 Functionele requirements In dit gedeelte zullen we een opsomming maken van de functionele requirements. We hebben deze requirements geprioriteerd aan de hand van de MoSCoW methode. 13.3.2.1 Must have 1. Alle communicatie met de RESTful API moet via een HTTPS verbinding gaan. 2. Elke resource moet (waar toepasselijk) de volgende HTTP methodes ondersteunen: GET, HEAD, PUT, POST, DELETE, OPTIONS. 3. Bij elk request die binnenkomt kan authenticatie informatie meegestuurd worden, in dat geval moet de server deze authenticeren. a. In het geval dat de authenticatie geldig is en de rechten van de geauthenticeerde reiken tot de actie die uitgevoerd moet worden dan zal deze ook worden uitgevoerd en het resultaat zal met de respons teruggestuurd worden. b. Als de authenticatie niet geldig is of onvoldoende rechten bezit zal de actie niet worden uitgevoerd en als gevolg zal de server een respons terugsturen met een foutmelding/foutcode om de reden voor het niet afhandelen kenbaar te maken aan de client. 4. Authenticatie kan geschieden met de HTTP basic methode, aangezien HTTPS gebruikt wordt. 5. Als er een GET request binnenkomt bij de server moet de resource (of een representatie daarvan) geretourneerd worden. 6. Als er een HEAD request binnenkomt bij de server moet dezelfde respons worden gegenereerd als bij de GET alleen wordt er geen body meegestuurd, dus alleen de meta-‐informatie zal in respons zitten. 7. De server moet expliciet in de respons headers meesturen of een resource cacheable is en wanneer de resource voor het laatst is gewijzigd. 8. De server moet clients in staat stellen om zoekopdrachten uit te voeren op de metadata op twee manieren: a. Simpel zoeken: er wordt één zoekterm opgegeven voor alle velden en de server retourneert alle persistent identifiers van datasets die overeenkomen met de zoekterm. b. Geavanceerd zoeken: er kunnen per metadata veld specifieke zoektermen opgegeven worden en de server retourneert alle matches. 9. Bij het opvragen van de data van een dataset kunnen twee situaties onstaan: a. Er wordt een enkel bestand opgevraagd: dit bestand wordt direct teruggestuurd met de respons. b. Er worden meerdere bestanden opgevraagd: de server zal de bestanden compresseren naar een zip bestand en deze meesturen met de respons. 13.3.2.2 Should have 10. Van een dataset moet het volgende adresseerbaar zijn:

56

10-‐07-‐2012


a. Data b. Metadata c. Activity log d. Jumpoff e. Permission requests f. Gebruikersovereenkomst(en) 11. Als er een PUT binnenkomt voor een resource die nog niet bestaat dan wordt deze aangemaakt aan de hand van de data in de body van de request. 12. Een POST request wordt gebruikt om een resource aan te maken in relatie tot een andere gegeven resource. De request bevat dus naast informatie over de aan te maken resource tevens informatie over de resource waarmee deze een relatie heeft. De nieuwe resource zal dus een kind zijn van de reeds bestaande resource. Er onstaat dus een ‘parent-‐child’ relatie. 13. Als er een OPTIONS request binnenkomt dan zal de server in de respons terugsturen welke van de HTTP methoden uitgevoerd kan worden op de gegeven resource. Met in acht neming van de meegestuurde ‘credentials’. 14. Depositors en archivarissen moeten van een bepaalde dataset de ‘permission requests’ kunnen adresseren. 15. Gebruikers moeten permissie kunnen aanvragen op restricted datasets. 16. Gebruikers moeten hun eigen ‘permission requests’ kunnen adresseren. 17. De zoekopdrachten moeten de lucene zoek-‐syntax in acht nemen (wildcards e.d.). 13.3.2.3 Could have 18. Bij het opvragen van de resources kan de client opgeven in welk formaat hij deze wenst te ontvangen, ondersteunde formaten zijn: a. XML/HTML b. JSON c. CSV 19. De gebruikersovereenkomst(en) van EASY moeten adresseerbaar zijn. 20. De gebruikersovereenkomst(en) van een dataset worden geleverd in het formaat waarin ze op de server staan. 21. Gebruikers moeten hun eigen profiel kunnen adresseren. 22. Hashes van resources moeten opgevraagd kunnen worden. 13.3.2.4 Won’t have 23. Gebruikers moeten zich kunnen registreren. 24. Als er een DELETE binnenkomt dan wordt de gegeven resource verwijderd. Afhankelijk van het type en staat van de resource zal deze: a. Daadwerkelijk verwijderd worden. b. De staat van de resource zal op ‘deleted’ worden gezet. 25. Als er een DELETE binnenkomt voor een resource die reeds in de staat ‘deleted’ is, dan wordt de resource gepurged (daadwerkelijk uit het systeem verwijderd).

57

10-‐07-‐2012


13.3.3 Non-‐functionele requirements In dit gedeelte komen de non-‐functionele requirements aan bod. Deze requirements zullen we opdelen in een aantal globale categorieën. 13.3.3.1 Usability 1. De REST en ROA principes moeten strict nageleefd worden. 2. De REST URI’s moeten natuurlijk vertalen naar de menselijke interpretatie van het pad naar de resource. 3. Er moet een handleiding worden geschreven voor derden die verduidelijkt hoe de communicatie met de REST API tot stand komt. 13.3.3.2 Reliability 4. De REST framework moet vervangbaar zijn door een alternatieve implementatie die voldoet aan de JAX-‐RS specificatie. 5. Geautomatiseerde tests moeten ontwikkeld worden en de code coverage van de tests mag niet lager liggen dan 75%. 13.3.3.3 Performance 6. De overhead die de REST API qua performance veroorzaakt mag niet meer dan 20% zijn van de responstijd die EASY nodig heeft voor het afhandelen van de actie. 7. Er moeten stresstests gedaan worden om te bepalen wat het breekpunt is van de API. 13.3.3.4 Supportability 8. Er moet een handleiding geschreven worden voor toekomstige ontwikkelaars die de API eventueel zullen aanpassen en/of uitbreiden. 9. De frameworks die gebruikt worden moeten actieve projecten zijn, zodanig dat er support verwacht kan worden van de online communities. 13.3.3.5 Implementation 10. De implementatie moet test-‐driven geschieden. 11. De code moet goed leesbaar en uitbreidbaar zijn. 12. De test suites moeten inzicht geven in de werking en mogelijkheden van de API.

58

10-‐07-‐2012


13.3.4 Systeem modellen In dit gedeelte zullen we het technisch ontwerp toelichten aan de hand van use-‐ cases en UML-‐diagrammen. 13.3.4.1 Scenarios We lichten de functies van de API in eerste instantie toe met use case beschrijvingen van de mogelijke scenarios. Deze beschrijvingen zijn geformuleerd voor resources in het algemeen en niet voor specifieke resources. Dit komt omdat we een uniforme interface hanteren waarbij de use cases gelijk zijn voor alle typen resources. Iedere respons van de API heeft een bepaalde HTTP respons code, die de status van het resultaat aangeeft. Het model voor deze respons codes is te zien in Appendix A. 13.3.4.1.1 UC – 01 – GET resource Brief This use case describes how a client can request a resource. Related use cases UC – 02 and UC – 03 Actor Client Parameters Path to a resource Main success scenario 1. The client sends a GET request 2. Server sends response corresponding to the GET request and HTTP response code 200 or 300 (if multiple representations are available for resource) Alternative scenario 1. Client sends a GET request 2. Server responds with HTTP response code 304 (resource has not been modified since last requested) Alternative scenario 1. Client sends a GET request 2. Server responds with HTTP response code 406 due to the requested resource not being conform to the Accept header Alternative scenario 1. Client sends a GET request 2. Server responds with HTTP response code 500 Extensions UC – 13 13.3.4.1.2 UC – 02 – search resources Brief This use case describes how a client can search for resources using the GET HTTP method Related use cases UC – 01 Actor Client

59

10-‐07-‐2012


Parameters Search criteria (e.g. title, author etc.) Main success scenario 1. The client sends a GET request with the search criteria 2. Server responds by listing all the pids (persistent identifiers) that match the search criteria Extensions UC – 01 13.3.4.1.3 UC – 03 – retrieve resource Brief This use case describes how a client can retrieve a resource using the GET HTTP method Related use cases UC – 01 Actor Client Parameters Resource path Preconditions Resource exists Main success scenario 1. Client sends request to get a resource 2. Server responds by returning the resource Extensions UC – 01 13.3.4.1.4 UC – 04 – OPTION resource Brief This use case describes how a client can determine what kind of HTTP methods a resource supports Actor Client Parameters Path to a resource Main success scenario 1. The client sends a OPTION request 2. Server responds by listing all supported HTTP methods of the resource and HTTP response code 200 13.3.4.1.5 UC – 05 – PUT resource Brief This use case describes how a client can PUT a resource Related use cases UC – 06 and UC – 07 Actor Client Parameters A resource Preconditions

60

10-‐07-‐2012


The given resource is valid Main success scenario 1. The client sends a PUT request 2. Server responds by adding or editing the resource Extensions UC – 13 13.3.4.1.6 UC – 06 – add resource Brief This use case describes how a client can add a resource using the HTTP PUT method Related use cases UC – 05 Actor Client Parameters A resource Preconditions Resource does not exist Main success scenario 1. The client sends a PUT request 2. Server responds by adding the resource and giving HTTP response code 201 or 303 (if new URI is provided) Alternative scenario 1. Client sends a PUT request 2. Server responds with HTTP status code 501 due to the fact that the server is not able to process the request Alternative scenario 1. Client sends a PUT request 2. Server responds with HTTP status code 500 Extensions UC – 05 13.3.4.1.7 UC – 07 – edit resource Brief This use case describes how a client can edit a resource using the HTTP PUT method Related use cases UC – 05 Actor Client Parameters A resource path Preconditions Resource already exists Main success scenario 1. The client sends a PUT request 2. Server responds by editing the existing resource and response code 204 Alternative scenario 1. Client sends a PUT request

61

10-‐07-‐2012


2. Server responds with HTTP status code 413 due to the request entity being too large Alternative scenario 1. Client sends a PUT request 2. Server responds with HTTP status code 501 due to the fact that the server is unable to process the request Alternative scenario 1. Client sends a PUT request 2. Server responds with HTTP status code 415 due to the request entity having a media type which is not supported by the resource or server Alternative scenario 1. Client sends a PUT request 2. Server responds with HTTP status code 500 Extensions UC – 05 13.3.4.1.8 UC – 08 – DELETE resource Brief This use case describes how a client can delete a resource Related use cases UC – 09 and UC – 10 Actor Client Parameters Path to the resource Preconditions The resource exists Main success scenario 1. The client sends a DELETE request 2. Server responds by deleting the existing resource using the response code 200 or 204 Alternative scenario 1. Client sends a DELETE request 2. Server responds with HTTP status code 500 Extensions UC – 13 13.3.4.1.9 UC – 09 – remove resource Brief This use case describes how a client can remove a resource using the DELETE HTTP method Related use cases UC – 08 Actor Client Parameters The resource path Preconditions Resource exists Main success scenario

62

10-‐07-‐2012


1. The client sends a delete request 2. Server responds by marking the resource for deletion Extensions UC – 08 13.3.4.1.10 UC – 10 – purge resource Brief This use case describes how a client can completely remove a resource using the DELETE HTTP method Related use cases UC – 08 Actor Client Parameters The resource path Preconditions UC – 09 Main success scenario 1. The client sends a DELETE request 2. Server responds by completely deleting the resource Extensions UC – 08 13.3.4.1.11 UC – 11 – HEAD resource Brief This use case describes how a client can retrieve the header of a request Actor Client Parameters Path to the resource Main success scenario 1. The client sends a HEAD request 2. Server responds by returning the header and HTTP response code 200 or 300 (if multiple representations are available for resource) Alternative scenario 1. Client sends a HEAD request 2. Server responds with HTTP response code 304 (resource has not been modified since last requested) Alternative scenario 1. Client sends a HEAD request 2. Server responds with HTTP response code 406 due to the requested resource not being conform the Accept header Alternative scenario 1. Client sends a HEAD request 2. Server responds with HTTP response code 500 Extensions UC – 13

63

10-‐07-‐2012


13.3.4.1.12 UC – 12 – POST resource Brief This use case describes how a client can POST a resource Related use cases Actor Client Parameters 1. Path to the ‘parent’ resource 2. The new subordinate resource Preconditions The parent resource exists Main success scenario 1. The client sends a POST request 2. Server responds by creating a subordinate resource and response code 201 or 303 (if new URI is provided) Alternative scenario 1. Client sends a POST request 2. Server responds with HTTP status code 404 if it does not permit doing a POST to the missing resource Alternative scenario 1. Client sends a POST request 2. Server responds with HTTP status code 501 due to the fact that the server lacks the ability to process the request Alternative scenario 1. Client sends a POST request 2. Server responds with HTTP status code 500 Extensions UC – 13 13.3.4.1.13 UC – 13 – Authorization Brief This use case describes how a client can be authorized Related use cases UC-‐01, UC-‐04, UC-‐05, UC-‐08 and UC-‐12 Actor Client Parameters 1. Username 2. Password Preconditions Username exists in userbase and password is valid for the given username Main success scenario 1. The client sends its credentials with the request header 2. Server responds with response code 200 Alternative scenario 1. The client sends its credentials with the request header 2. Server responds with response code 401 Unauthorized

64

10-‐07-‐2012


13.3.4.2 Use case model Figuur 18 toont het use case diagram voor de REST API. Deze use cases hebben betrekking op alle typen resources die in het systeem aanwezig zijn.

Figuur 18: Use case diagram REST API

65

10-‐07-‐2012


13.3.4.3 Analysis object model

Figuur 19: klassendiagram REST API

66

10-‐07-‐2012


13.3.4.4 Dynamic model Voor een aantal karakteristieke scenarios hebben we sequence diagrammen opgesteld die de interne stroom van data en functies visualizeren. Deze diagrammen zullen samen met het klassendiagram een centrale rol spelen bij het implementeren van de API. De opgestelde sequence diagrammen zijn te zien in figuur 20 t/m 26.

Figuur 20: Metadata van een dataset opvragen

Figuur 21: Registreren van een nieuwe gebruiker

67

10-‐07-‐2012


Figuur 22: Opvragen of een bepaalde dataset bestaat

Figuur 23: Opvragen welke methodes van toepassing zijn op de search resource

68

10-‐07-‐2012


Figuur 24: Verwijderen van een dataset

Figuur 25: Uitvoeren van een advanced search

Figuur 26: Updaten van metadata

69

10-‐07-‐2012


13.3.4.5 Interface De API heeft vanzelfsprekend geen grafische interface maar een communicatieve interface. De communicatie gebeurt op basis van het HTTP protocol en de URI’s die gehanteerd worden hebben de leidende functie als het gaat om de helderheid en bruikbaarheid van de interface. Onderstaand tabel toont de mapping van resources op URI’s. Resource

URI

Dataset metadata Specifiek veld uit metadata Dataset data Specifieke map Specifiek bestand Bestands metadata Bestands hash Jumpoff pagina Dataset condities Activity log Simpel zoeken

/dataset//metadata /dataset//metadata/

Geavanceerd zoeken Algemene voorwaarden Gebruikers Specifieke gebruiker Specifiek veld van gebruiker

/dataset//data /dataset//data/ /dataset//data// /dataset//data///metadata /dataset//data///hash /dataset//jumpoff /dataset//conditions /dataset//activity?y=&m=<month> /search?q= /search?=&…&= /dans/conditions /users /user/ /user//

Tabel 1: Mapping van resources op URI’s

70

10-‐07-‐2012


13.4 Woordenlijst API – Application Programming Interface, een verzameling definities waarbinnen computerprogramma’s met elkaar communiceren. Code coverage – Een methode voor meting gebruikt bij het testen van software. Het beschrijft het bereik van de tests in de code van het te testen systeem. Functionele requirement – Een beschrijving van specifiek gedrag of functie, die het systeem dient te vervullen. HTTP – Hypertext Transfer Protocol, een protocol voor de communicatie tussen een webclient en een webserver. JAX-RS – Een Java API die ondersteuning verschaft voor het opzetten van web services volgens het REST architectuur principe. Mashup – Een mashup is een webpagina of –applicatie waar gegevens uit meerdere bronnen gecombineerd en gezamelijk gepresenteerd worden. MoSCoW – Een wijze van prioriteiten stellen voor requirements. Niet-functionele requirement – Criteria om het functioneren van het systeem te beoordelen, echter geen beschrijving van specifiek gedrag. Representatie – Weergave van een resource. Resource – Elk stukje interessante informatie in een systeem. REST – Representational state transfer, een architectuur principe voor het inrichten van webservices. ROA – Resource Oriented Architecure, een uitbreiding op het REST principe. Stresstest – Een testvorm waarbij de stabiliteit van een geheel systeem wordt getest. UML – Unified Modeling Language, een modelmatige taal om objectgeoriënteerde analyses en ontwerpen voor een informatiesysteem te kunnen maken. URI – Uniform Resource Identifier, een internet-‐protocolelement voor het lokaliseren van resources op het web. Use case – Een beschrijving van een gedrag van een systeem, dat reageert op een verzoek dat stamt van buiten het systeem.

71

10-‐07-‐2012


13.5 (RAD-‐API) Appendix A – HTTP respons codes

72

10-‐07-‐2012


14 Appendix E – Requirements Analysis Document -‐ Client

14.1 Voorwoord In dit document wordt beschreven welke functionaliteiten de demonstrator(s) moeten hebben. De te implementeren functionaliteiten zijn door zowel Maarten Hoogerwerf als zijn collega’s bij DANS voorgesteld. In verband met de tijdsduur van dit bachelorproject is het helaas niet mogelijk om alle voorgestelde functionaliteiten te implementeren. 14.2 Introductie 14.2.1 Doel van de demonstrator De demonstrator wordt zodanig ontworpen, zodat deze de geïmplementeerde API functies valideert op de werking. Tevens zal de demonstrator aantonen dat het mogelijk is om de data die door de API beschikbaar is gesteld in een andere context te gebruiken (bijvoorbeeld in een mobiele applicatie). Wat in het verlengde van het bovengenoemde is het combineren van andere databronnen met de data die in EASY zitten door middel van de API. 14.2.2 Scope van de demonstrator Na gesproken te hebben met mogelijke klanten van de Restful API, zijn de volgende use-‐cases betreffende de demonstrator naar voren gekomen: 1. Het grafisch weergeven van datasets op een kaart door middel van de coördinaten die in de metadata zitten. 2. Het grafisch weergeven van datasets op een tijdslijn door middel van de tijdsperiode die gegeven zijn in de metadata. 3. De relaties tussen verschillende datasets grafisch weergeven. 4. Het tonen van data, gegeven een bepaald formaat (bijvoorbeeld een Comma-‐separated values54 bestand). 5. Een tool-‐kit die ervoor zorgt dat de data voldoet aan bepaalde standaarden 6. Het gebruik van een mobiele toepassing met betrekking tot de data 7. Het combineren van verschillende databronnen In verband met de gegeven tijd van dit bachelorproject is het vrijwel onmogelijk om alle zeven functionaliteiten te implementeren. Derhalve hebben we besloten om een combinatie van use-‐cases te implementeren. De use-‐cases die gecombineerd gaan worden zijn use-‐case 1,2,6,7. 14.2.3 Doelen en succes-‐ criteria van het project Elke dataset, waarvan de coördinaten gegeven zijn in de metadata (over het algemeen zijn dit archeologische datasets), zal weergeven worden op de “google maps” door middel van een markering. Als er vervolgens op een markering 54 http://en.wikipedia.org/wiki/Comma-‐separated_values

73

10-‐07-‐2012


wordt geklikt zal er een korte beschrijving van de betreffende dataset verschijnen en een link met een ID zal zichtbaar zijn, om eventueel de dataset in EASY te bekijken. Als er vervolgens nieuw onderzoek gedeponeerd wordt in EASY (waarvan in de metadata de coördinaten zijn ingevuld) zal deze tevens op de kaart zichtbaar zijn. Wanneer een onderzoek gedeponeerd wordt in EASY kan de onderzoeker specificeren over welke tijdsperiode het onderzoek van toepassing is (bijvoorbeeld Nieuwe tijd). De tweede applicatie zal door middel van de laatsgenoemde data een tijdslijn construeren waarop datasets geplaatst zijn. De eindgebruiker zal kunnen inzoomen op een bepaalde tijdsperiode en een gewenste dataset opvragen. Beide implementatie zullen geacht worden te draaien op een mobiele applicatie.

14.2.4 Overzicht

Dit document is als volgt opgebouwd: eerst wordt er bekeken of er binnen DANS niet al faciliteiten worden geboden voor de bovengenoemde functionaliteiten. Vervolgens worden er UML diagrammen geconstrueerd ter verduidelijking van het technisch ontwerp en de wijze waarop we de implementatie zullen realiseren.

14.3 Huidige implementaties Er zijn al wat implementaties beschikbaar voor het “grafisch weergeven van datasets op een kaart” en het “grafisch weergeven van datasets op een tijdslijn”. Echter zijn deze implementaties gemaakt als een proof of concept. Kenmerkend voor beide implementaties zijn dat de data statisch worden ingeladen. 14.3.1 Grafisch weergeven van datasets op een kaart Omdat de data handmatig ingevoerd moet worden, wordt de data dus niet real-‐ time opgehaald van EASY. Voor elke nieuwe dataset moeten deze handmatig worden geupdate in een kml (Keyhole Markup Language)55 bestand om op een kaart zichtbaar te zijn. In het huidig systeem bestaan er drie kml bestanden. Eén van de kml bestanden bevat alleen de onderzoeken die van toepassing zijn op het noorden van Nederland. De overige twee kml betanden zijn respectievelijke van toepassing op het midden en het zuiden van Nederland. Over het algemeen worden de coördinaten volgens de standaard van de Rijksdriehoek coördinaten in EASY opgeslagen. Google Maps daarentegen bepaald door middel van de latitude en de longitude een locatie. De convertatie algoritme van verschillende coördinatenstelsels is al beschreven in een excel bestand.

55 http://en.wikipedia.org/wiki/Keyhole_Markup_Language

74

10-‐07-‐2012


Figuur 27: Een aantal datasets van midden nederland weergeven op een kaart.

14.3.2 Grafisch weergeven van datasets op een tijdlijn Het “grafisch weergeven van datasets op een tijdlijn” is evenals de laatstgenoemde functionaliteit geïmplementeerd in het huidige systeem. De tijdslijn werkt als het ware als een zoekfunctie binnen EASY op een tijdsperiode. De tijdslijn kan onderverdeeld worden in de volgende negen periodes: • Paleolithicum • Mesolithicum • Neolithicum • Bronstijd • IJzertijd • Romeinse tijd • Middeleeuwen • Nieuwe tijd • Heden Elk van deze tijdsperiodes is weer onderverdeeld in subperiodes. Zo is de Nieuwe tijd (1500-heden) onderverdeelbaar in: Nieuwe tijd A (1500-1650), Nieuwe tijd B (1650-1850) en Nieuwe tijd C (1850-heden) . Als de eindgebruiker de datasets corresponderend met de Nieuwe tijd wenst te zien, klikt de eindgebruiker op de Nieuwe tijd link. Dit heeft als gevolg dat er een zoekquery wordt gestuurd met als parameter de tijdsperiodes Nieuwe tijd, Nieuwe tijd A, Nieuwe tijd B en Nieuwe tijd C. Als de eindgebruiker alleen geïnteresseerd is in een subperiode van de Nieuwe tijd, bijvoorbeeld Nieuwe tijd C, wordt er respectievelijk een zoekquery gestuurd met alleen de parameter Nieuwe tijd C.

75

10-‐07-‐2012


Figuur 28: Tijdslijn gecentreerd op de ‘Nieuwe tijd’.

14.4 Voorgesteld Systeem 14.4.1 Grafisch weergeven van datasets op een kaart In eerste instantie zullen we de huidige implementatie als leidraad gebruiken voor onze implementatie op het Android platform. Echter zijn we van plan om nog extra functionaliteiten toe te voegen. Naast het weergeven van de relevante metadata, willen we faciliteren dat tevens de data zichtbaar gemaakt kan worden. Als bij de data bijvoorbeeld een afbeelding beschikbaar is, zal deze weergeven worden. Om de informatie van de metadata aan te vullen zal gebruik worden gemaakt van DBpedia56 als databron. Een archeologische dataset kan nul dan wel meerdere coördinaten bevatten. Het filteren op datasets welke coördinaten bevatten, geschied door middel van het gebruik van de resource /search?q=scheme=rd die door de Restful API beschikbaar is gesteld (op het moment van schrijven heeft EASY 12,214 datasets waarvan 1 of meer coördinaten zijn ingevuld). De demonstrator zal de zoekresultaten in een kml bestand plaatsen. Vervolgens kan de laatstgenoemde kml geïnterpreteerd worden door Google Maps/Earth. Om de performance van de applicatie relatief hoog te houden zal er gebruik worden gemaakt van de zogenoemde “Lazy loading”57 design pattern. In ons geval zal dit als volgt worden geïmplementeerd: -‐ De metadata van een dataset en relevante externe bronnen zullen alleen worden opgehaald als op diens markering is geklikt. -‐ Er worden alleen datasets ingeladen die zichtbaar zijn op het scherm. 56 http://dbpedia.org/About 57 http://en.wikipedia.org/wiki/Lazy_loading

76

10-‐07-‐2012


14.4.2 Grafisch weergeven van datasets op een tijdslijn Net zoals de bovenstaande functionaliteit gebruiken we de huidige implementatie van het “grafisch weergeven van datasets op een tijdslijn” als referentie. Door het gebruik van informatie dat wordt verstrekt door derden kunnen we ook bij de implementatie van deze functionaliteit de (meta)data combineren om zodanig een mashup te creëren. Enkele externe bronnen die de meerwaarde ten goede zullen beïnvloeden zijn (de eerder genoemde) DBpedia en/of Geonames58. Evenals de bovenstaande functionalteit zal tevens hier gebruik worden gemaakt van de “Lazy loading” design pattern, om de workload te beperken. Voor deze functionaliteit zal dit als volgt worden geïmplementeerd: -‐ De metadata van een dataset en relevante externe bronnen zullen alleen worden opgehaald als op diens markering is geklikt. -‐ Alleen datasets inladen voor een geselecteerde tijdsperiode. De demonstrator zal een tijdslijn construeren met tijdsperiodes die van toepassing zijn op EASY. Als er op een bepaalde tijdsperiode of een jaar wordt geklikt zal er een /search?q=X request gestuurd worden naar de Restful API (waarbij X een tijdsperiode is). Als er op een bepaalde jaar geklikt wordt zal er Een search request gestuurd met de tijdsperiode die van toepassing is op de betreffende jaar. Risico: Het is nog niet helemaal duidelijk of de timeline functionaliteit in de Android omgeving zal kunnen draaien. Dit komt doordat de huidige tijdlijn functionaliteit ontwikkeld is in javascript en de app moet worden ontwikkeld in java. Tevens zijn veel libraries die tijdlijnen implementeren in javascript of HTML5 ontwikkeld, we hebben er nog geen gevonden die in java is ontwikkeld en werkt onder Android. We zullen onderzoeken hoe we dit probleem kunnen oplossen.

14.5 Systeem modellen

In dit hoofdstuk wijden we de interne structuur van de applicaties uit. Dit doen we door middel van UML diagrammen en scenarios. 14.5.1 Scenarios 14.5.1.1.1 UC – 01 – View map Brief This use case describes how a map with datasets is viewed to the user. Actor User Main success scenario 3. The user presses a button which starts the activity of viewing the map 4. The client then in turn sends a GET request on the resource “/map” 5. As a response data is returned in a kml format, which can be interpreted by Google Maps/Earth 6. Map with corresponding kml data is outputted to the user Alternative scenario 2. Server responds with a different response code than 200 58 http://www.geonames.org/

77

10-‐07-‐2012


Alternative scenario 3. Kml file cannot be interpreted by the Google Maps/Earth application 14.5.1.1.2 UC – 02 – View location Brief This use case describes how a user can search for datasets with the aid of a timeline Actor User Main success scenario 3. The user presses a button which starts the activity of viewing the timeline 4. The client sends a GET request on the resource “/timeline” 5. Server generates a response. With which the client can then in turn construct the timeline. Alternative scenario 3. Server responds with a different response code than 200 14.5.2 Use case model

Figuur 29: Use case diagram van de clientapplicaties.

78

10-‐07-‐2012


14.5.3 Analysis object model

Figuur 30: Klassendiagram van de client applicaties.

79

10-‐07-‐2012


14.5.4 Dynamic model

Figuur 31: Sequence diagram van het inladen van datasets op een kaart.

Figuur 32: Sequence diagram voor het inladen van datasets op een tijdlijn.

80

10-‐07-‐2012


15 Appendix F – Web Application Description Language (WADL) beschrijving API <doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 1.8 06/24/2011 12:17 PM"/> <method name="GET" id="helloUser"> <method name="GET" id="hello"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <method name="GET" id="getData"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <method name="GET" id="getDcMetadata"> <method name="OPTIONS" id="optionsDcMetadata"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <method name="GET" id="getMetadata"> <method name="OPTIONS" id="optionsMetadata">

81

10-‐07-‐2012


<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <method name="GET" id="getJumpoff"> <method name="OPTIONS" id="optionsJumpoff"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <method name="GET" id="getJumpoffMetadata"> <method name="OPTIONS" id="optionsJumpoffMetadata"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="path"/> <method name="GET" id="getFileItemMetadataWithPath"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="path"/> <method name="GET" id="getDcFileItemMetadataWithPath"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <method name="GET" id="getFileTreeRoots"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="folderSid"/> <method name="GET" id="getFolderSubTree">

82

10-‐07-‐2012


<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <method name="GET" id="getThumbnailIds"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="thumbnailSid"/> <method name="GET" id="getThumbnail"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="path"/> <method name="GET" id="getSpecificDataWithPath"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="fileSid"/> <method name="GET" id="getSpecificFileWithId"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="folderSid"/> <method name="GET" id="getSpecificFolderWithId"> <method name="GET" id="getDisciplines">

83

10-‐07-‐2012


<param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <method name="GET" id="getDisciplineBySid"> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="sid"/> <method name="GET" id="getSubDisciplines"> <method name="GET" id="getRootDisciplines"> <method name="GET" id="getAccount"> <method name="GET" id="getDatasets"> <method name="GET" id="search"> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="" type="xs:string" style="query" name="q"/> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="0" type="xs:int" style="query" name="offset"/> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="10" type="xs:int" style="query" name="limit"/> <method name="GET" id="search"> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="0" type="xs:int" style="query" name="offset"/> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="10" type="xs:int" style="query" name="limit"/>

84

10-‐07-‐2012


85

EWI. BSc- project EASY REST API EN DEMONSTRATOR IN3405. Data Archiving and Networked Services

Recommend Documents