Slutrapport: Coleo projekthanteringsverktygs webbapi

Transkript

1 Slutrapport: Coleo projekthanteringsverktygs webbapi Webbprojekt I, 1DV Medverkande: Peter Persson Cem Kirman Annie Johansson Andreas Larsson Kurskod: 1DV411

2 Sammanfattning Coleo är ett webbaserat projektverktyg där du enkelt och effektivt kan både planera och genomföra dina projekt. Coleo är en molntjänst vilket gör att du får en komplett lösning utan att behöva installera något på din dator eller server. Nästa steg för Coleo är att kunna erbjuda sin tjänst till sina kunder via ett webb API, så att de kan utveckla egna applikationer, bygga in Coleos projekthanteringssystem i deras andra system eller liknande. I samband med kursen Webbprojekt I skapades ett RESTful Webb API. Denna rapport beskriver utvecklingen av produkten, resultatet, vilka tekniker som använts, samt svårigheter under projektets gång. I

3 Förord Genom kursansvarig Tobias Ohlsson i 1DV411 Webbprojekt, 7.5 hp tilldelades vi i gruppen att under 10 veckor på halvfart utveckla ett RESTful Web Api till Coleo s projekthanteringssystem. Till vår hjälp har vi haft vår handledare Martin Fredriksson och uppdragsgivaren Marcus Oldin och Pelle Sederkvist hos Coleo. Vi vill passa på att tacka alla berörda för ett bra samarbete. II

4 Innehållsförteckning Sammanfattning... I Förord...II 1. Introduktion Bakgrund Beskrivning RavenDB ASP.NET MVC Autentisiering Enhetstester Syfte Mål Projektorganisation Genomförande Metodik Dokumentation Unified Process V 3 Uppstart V 4-5 Inception V 6-7 Elaboration V 8-10 Construction V 11 Transition Tårtkalas Kundkontakt Teknik Programmeringsspråk Programvara Resultat Ramverk Övergripande om.net MVC4 ramverket Application_Start och Configure-metoderna Routing och styrning av förfrågningar inom systemet III

5 4.1.4 Kontrollers och dataflöden Modeller Autentisering Slutsats Förslag på vidareutveckling Övertagande av organisation Förslag till förbättringar inför kommande projekt IV

6 1. Introduktion 1.1 Bakgrund Coleo tillhandahåller ett webbaserat projektverktyg för företag där man enkelt och effektivt kan planera och genomföra sina projekt. Coleo kontaktade Linnéuniversitetet då de behövde hjälp med att vidareutveckla sin produkt och kunna erbjuda ett Web API för sina kunder. Coleos samarbete med LNU i formen av projektarbeten sträcker sig utanför omfånget av detta projekt och involverar även ytterligare en grupp av Webbprogrammerare som har fått i uppgift att skapa ett mobiltgränssnitt mot Coleos verktyg, samt en grupp med Interaktions designers som ska säkerställa informationsflöden samt användarvänlighet i applikationen. Initialt hade Coleo som avsikt att mobilapplikationen skulle hämta och manipulera data med hjälp av det webb API som vi avsåg skapa. Detta visade sig vara svårimplementerat främst på grund av autentiseringsförfarandet men även på grund av att mobilapplikationens databehov sträckte sig utanför det data APIet tillhandahåller. 1.2 Beskrivning RavenDB Coleo använder sig idag av RavenDB för persistent lagring av data. Raven är en NoSQL databas där alla objekt sparas som JSON objekt. Integrationslösningar för ASP.NET ramverket och IIS finns att tillgå ASP.NET MVC 4 Inledningsvis uttryckte Coleo önskemål om att APIet skulle skapas med hjälp av Ramverket WCF, Windows Communication Foundation, ett hjälpramverk för att skapa webb APIer med RESTful gränsnitt. Halvvägs in i projektet lanserade Microsoft en Beta release av ASP.NET MVC 4 och Coleo uttalade då ett önskemål om att lyfta över implementationen dit. MVC 4 har inbyggd funktionalitet för att hantera webb APIer, vilket resulterade i att vi fick börja om och skapa funktionaliteten på nytt. Vi såg dock detta som en utmaning snarare än ett hinder. Alla delade ett 1

7 gemensamt intresse för möjligheten att fördjupa sig i det nya ramverket och dess inbyggda funktionalitet för att skapa ett webb API. Resultatet blev enklare, mer intuitiv och renare kod som är enkel att refaktorera eller bygga ut Autentisiering En modell framtagen av Amazon för att autentisera användare av webbapier har implementerats och säkerställer att information inte kan läsas eller manipuleras av personer som inte ingår i organisationen som äger uppgifterna Enhetstester APIet implementerar en autentisering av organisationen som står bakom förfrågan genom kryptering av data som bifogas i requestheadern. Den krypterade datan som bara kan dekrypteras av Organisationen som har den privata nyckeln, samt Coleo som har tillgång till samma nyckel, säkerställer att informationen inte hamnar i fel händer. Men det medförde även att APIet inte längre kan testat med hjälp av exempelvis Fiddler som vi använde inledningsvis i projektet, detta eftersom Fiddler inte har funktionalitet för att kryptera autentiseringsdata. Vi har alltså skapat en testsvit i Visual Studio som testar samtliga HttpVerb och resurser som projektet är tilldelat att tillhandahålla. 1.3 Syfte Det huvudsakliga syftet är att Coleo expanderar och vill kunna erbjuda sina kunder ett enkelt och smidigt sätt att bygga in projekthanteringssystemet i sina egna system, utveckla egna applikationer eller för att ta del av informationen av andra anledningar. Lösningen på detta är att kunna erbjuda ett lättanvänt Webb API, där man enkelt ska kunna hantera det vardagliga arbetet i Coleos projekthanteringsverktyg. Coleo har en idé på hur det bör fungera, projektgruppens uppgift blir att hitta bästa lösningen. Då detta projekt genomförs av studenter vid Webbprogrammerarprogrammet är syftet även att vi ska införskaffa erfarenheter av att arbeta i grupp under en anpassad variant av Unified Process. Detta innefattar bland annat att hantera dokument, tidrapportering, roterande schema för de olika rollerna i projektet så som projektledare, dokumentationsansvarig etc. 2

8 1.4 Mål Det övergripande målet med projektet är att skapa ett säkert Webb API som är enkelt, intuitivt och smidig att arbeta mot och som följer REST. Utöver att Api:et ska fungera på ett bra sätt ska det även vara enkelt för Coleo att i efterhand utöka funktionaliteten med fler funktionalitet utan att behöva skriva om och ändra i befintlig kod. De baskrav som ålades oss att implementera i form av resurser som ska tillhandahållas via APIet var: Departments o Hämta alla avdelningar o Hämta enskild avdelning Aktiviteter o Hämta alla aktiviteter o Hämta enskild aktivitet o Skapa aktivitet o Uppdatera aktivitet o Radera aktivitet Logitems o Hämta alla logitems o Hämta enskild logitem o Hämta alla logitems under en specifik användare o Hämta alla logitems under en specifik user o Skapa logitem o Uppdatera logitem o Radera logitem User o Hämta alla användare o Hämta specifik användare o Hämta alla användare under en specifik department o Hämta alla användare under en specifik aktivitet En form av autentisering av användaren har även implementerats för att säkerställa att ingen information kommer i fel händer. 3

9 Autentiseringen medför även att man bara kan hantera data tillhörande en specifik organisation per förfrågan via HTTPprotokollet, vilket medför svårigheter för Mobilapplikationsgruppen att utveckla mot APIet. 4

10 2. Projektorganisation Kursansvarig: Tobias Ohlsson Handledare: Martin Fredriksson Kund: Coleo Projektgrupp: Annie Johansson, Peter Persson, Cem Kirman, Andreas Larsson Projektgruppen har haft roterande schema för Projektledning samt övriga roller, rotation har skett veckovis. Varje vecka genomfördes möten med handledare respektive kund. Basstrukturen för Projektorganisationen var organiserad enligt bilden nedan. 5

11 3. Genomförande 3.1 Metodik Projektet har genomförts iterativt. Varje iteration omfattade en vecka som inleddes med ett handledarmöte där iterationsplanen samt annan skapad eller underhållen dokumentation gicks igenom, vi gick även igenom föregående protokoll och diskuterade problem som uppstått. Vid slutet av varje vecka utsågs en ny projektledare för kommande vecka, som ansvarade för att iterationsplanen efterlevdes och underhölls. Förutom handledarmöten har vi inom gruppen genomfört flertalet möten varje vecka för att diskutera och implementera kod samt skapa och underhålla dokumentation. Då vi under projektet har stött på tre helt nya tekniker för oss (RavenDB, WCF och ASP.NET MVC 4 Web Api) har vi ofta suttit och utvecklat tillsammans, dels för att lära oss och dels för att få olika infallsvinklar på hur man implementerar koden på bästa sätt. Hade det varit tekniker vi redan kände till och behärskade hade vi sannolikt delat upp kodandet mellan oss på ett smidigare sätt. Från och med v 6 avslutades varje iterations med att vi gjorde en delleverans till kunden samt ett möte där vi diskuterade framgångar och motgångar under den gångna veckan. Vår kund har varit tillgänglig och gärna svarat på frågor och gett oss feedback under hela projekttiden och samarbetet har varit väldigt smidigt och problemfritt. Då vi arbetat iterativt har vi haft en del levande dokument och kod. För att hantera detta på ett bra sätt och inte skriva över varandras dokument har vi använt oss utav versionshantering med hjälp av SVN Tortoise samt BitBucket och DropBox Dokumentation Projektet har producerat dokument för att täcka och avhandla information rörande: Projektvision, övergripande beskrivning av bakgrund syfte och mål, samt baskrav för projektet. Kravspecifikation, en lista med funktionella krav som iterativt har utökats med användningsfall som beskriver den funktionalitet som Coleo eftersöker i sitt webb API. Testspecifikation, ett dokument med testfall som ska säkerställa att funktionalitet enligt Kravspecifikationen implementeras. Testrapporter med veckovis utfall av testerna i testspecifikationen. 6

12 Mjukvaruarkitektur, ett dokument där vi valt ut tre specifika baskrav och i detalj beskrivit hur dessa ska implementeras för att på så sätt underlätta implementation av återstoden av krav på ett snarlikt sätt. Strategiska planer för: Projektet Planering Utveckling Dokumentation Leverans Acceptanstest som signerats av kund där vi på ett mycket specifikt sätt kommer överens om vad som ska anses vara en acceptabel slutleverans av projektet. Risklista som tydliggör och prioriterar risker inom projektet. Iterationsplan, för tydlig struktur och planering varje iteration Unified Process Projektet har bedrivits och genomförts i en för Linneuniversitetet speciellt framtagen version av Unified Process. Projektet har innefattat delat ansvar inom fyra projektområden, Planering, Utveckling, Dokumentation och Leverans. Samtliga deltagare har turats om att ansvara för var och ett av dessa ansvarsområden med veckovis rotation. Vi har även inom projektet använt oss av en från projektmetoden Scrum lånad modell för veckovis iterationsplanering samt tidsredovisning i form av Iterationsplan och burndownchart. Projektet har bedrivits enligt nedan: V 3 Uppstart Vecka 3 ägnades åt att ta en första kontakt med kund för att få en övergripande bild av problemet. Vi hade även vårt första gruppmöte och bekantade oss med varandra och diskuterade kring hur vi skulle lägga upp arbetsfördelning osv. Något som senare i projektet mer eller mindre föll på plats helt naturligt med en rättvis och jämn spridning av arbetsuppgifter inom samtliga arbetsområden V 4-5 Inception Under v4 genomförde vi vårt första handledarmöte. Vi påbörjade även arbetet med Vision samt kravspecifikation. En risklista skapades men saknade dock i princip innehåll så här tidigt i 7

13 projektet. Det fastställdes att kunden önskade utveckling i ASP.NET MVC 3 med hjälp av RavenDB och WCF för API funktionalitet. Under v5 färdigställdes och godkändes Visionen av kund, vi studerade det nya ramverket WCF och NoSQLDatabasen Raven för att förstå hur vi skulle implementera vår kod V 6-7 Elaboration Vecka 6 och 7 fylldes av test-implementation av WCF applikationer med RavenDB för att förstå hur de båda på bästa sätt skulle struktureras för att arbeta tillfredställande tillsammans. Vi följde tutorials och guider på nätet och etablerade även en bra kodbas för vår produkt. Enklare tester genomfördes och krav- samt testspecifikationslistorna började falla på plats. Dessa kunde vi relativt tidigt färdigställa eftersom vi hade tydliga krav på funktionalitet inom APIet, vilken data som skulle göras tillgäng och vilken data som skulle kunna manipuleras etc V 8-10 Construction I vecka 8 introducerade kunden Coleo önskemål om att lyfta over implementerad kodbas i det nyss släppta ramverket ASP.NET MVC 4 med sitt inbyggda stöd för webb API. Vi undersökte de tekniska svårigheterna som skulle kunna uppstå och beslutade oss gemensamt för att vi var intresserade av att utforska det nya ramverket och lära oss den nya funktionalitet det erbjöd. Vi påbörjade därför arbetet med att skapa vår applikation igen från grunden. Detta visade sig vara ett bra beslut då ramverket gav oss många fördelar och en enklare struktur för implementation av resursåtkomst etc. enligt det väl etablerade MVC arkitekturen som WCF inte riktigt levde upp till. Applikationen kunde slutföras och dokumenteras V 11 Transition Tårtkalas Sluttester av systemet, färdigställande av dokumentation i såväl APIet som projektet med genomgång av samtliga dokument, tester och rapporter för att säkerställa att alla bitarna var på plats. Veckan kröntes med en synnerligen framgångsrik slutleverans av produkten till kund! Kundkontakt Coleo har på ett mycket bra sätt varit kontaktbara via Skype och mail under hela projektet vilket har medfört att vi direkt när problem har uppstått enkelt har kunnat lufta dessa med antingen Pelle, när det rörde Coleo i stort, eller Marcus gällande kod och implementation. Marcus är även 8

14 väl insatt i ASP.NET vilket har gjort det enkelt att få snabba och bra svar gällande programmeringsrelaterade problem. 3.2 Teknik Programmeringsspråk Coleos webbapplikation är skriven med ASP.NET MVC 3, C# och NoSql-databasen RavenDB. För att på ett smidigt sätt kunna arbeta med den befintliga datamodellen och på ett enkelt sätt kunna integrera Api:et med applikationen använde vi ASP.NET MVC 4 Web Api. Då ASP.NET MVC 4 släpptes under projektets gång påbörjade vi implementationen med att utveckla Api:et med hjälp av Windows Communication Foundation. Vi bytte teknik dels på grund utav att kunden gärna ville använda den nya tekniken, och dels för att det i slutändan underlättade vårt arbete. Det blir även enklare för kunden att implementera Api:et vid användare av ASP.NET MVC 4 Web Api Programvara All programmering skedde i Visual Studio 2010 och Visual Studio 11. För testning av Api:et har vi använt oss av Fiddler 2, ett program där man enkelt kan bygga upp Http Request och få en utförlig beskrivning av responsen. För versionshantering av kod och dokument har vi använt Tortoise SVN, BitBucket. Vid leverans till kund har vi använt DropBox. Då projektet utförts på distans mellan projektmedlemmarna har Skype, Adobe Connect och Yammer använts flitigt. 9

15 4. Resultat 4.1 Ramverk Övergripande om.net MVC4 ramverket Arbetet med ASP.NET visade sig vara väldigt smidigt och erbjöd en systemarkitektur enligt Model View Controller som vi alla var bekanta med. Även om vi inte renderar ut vyer i klassisk bemärkelse, eftersom vi endast tillhandahåller resurser i dataformaten XML och JSON och inget grafiskt gränssnitt har utvecklats. Ramverket har inbyggd funktionalitet för att behandla HTTPRequests och de olika verben GET, PUT, POST, DELETE samt all eventuell data som bifogas i requestbodyn. Även funktionalitet för att generera ett korrekt Respons-message med tillhörande Respons-code är inbyggt och användarvänligt att utveckla mot Application_Start och Configure-metoderna Metoden Application_Start körs första gången en applikation startas. Här ser vi till så att kopplingen till databasen och våra olika konfigurationer skapas. I Configure lägger vi till ett valideringsfilter, så vid varje förfrågan med indata kommer valideringsfiltret att köra och validera indatat. Även autentisieringen läggs till här och den sker vid varje request. 10

16 4.1.3 Routing och styrning av förfrågningar inom systemet Ramverket analyserar den HTTP Request som skickas till systemet. Förfrågan blir vidarebefordrad in i systemet till rätt Kontroller som i sin tur har direktkontakt med rätt Modelklass i databsen och kan tillhandahålla rätt information enligt det som efterfrågas i requesten. Bilden nedan visar hur routingen för att hämta ut eller manipulera data i aktiviteter inom projekthanteringsverktyget ser ut. Bilden visar: hämta samtliga aktiviteter, en specifik aktivitets underaktiviteter, en specifik aktivitets användare, en specifik aktivitets logitems och slutligen hur man hämtar ut en specifik aktivitet Kontrollers och dataflöden Att arbeta med RavenDb innebär en liten annan implementation än när man t.ex. jobbar mot en MS SQL-databas. Kort kan man säga att under en applikations livscykel ska man endast instansiera en så kallad DocumentStore för att arbeta mot databasen. Detta gör man lämpligtvis i Application_Start. Mot DocumentStore:n ställer man sina frågor till databasen. Det gör man genom att öppna en session för varje förfrågan, för att därefter stänga den igen. Vi skapade därför en bas-kontroller som övriga api-kontroller ärver ifrån. I den här kontrollerns Initialize-metod öppnar vi sessionen. Bas-kontrollern ärver i sin tur från den i Ramverket inbyggda ApiControllern som ger oss tillgång till all ovan nämnda funktionalitet. 11

17 Den specifika Kontrollermetoden som exekveras i anropad kontroller följer ett tydligt mönster som vi etablerade under utformningen av Mjukvaruarkitekturen. Flödet inleds med att säkerställa att efterfrågad resurs tillhör Autentiserad organisation, säkerställer att den inte har status deleted = true, gör ändringar enligt http verbet som används och returnerar sedan ett HttpResponsMessage objekt innehållande det efterfrågade eller påverkade objektet samt en statuskod. Bilden nedan visar Kontrollerflödet vid en DELETE förfrågan mot en specifik aktivitet inom projekthanteringsverktyget: Modeller Samtliga modellklasser var redan specificerade och tillhandahölls i befintligt skick av Coleo. Vi ger tillträde till resurser enligt baskraven, i fullständigt obehandlat skick. Coleo har senare för avsikt att strypa datan som ska skickas ut genom APIet Autentisering För att skydda obehöriga från att komma åt api:et har vi implementerat en autentisering enligt en modell som bland annat Amazon.com använder sig av. Autentisering sker via en metod som kallas HMAC, Hash-Based Message Authentication Code. Varje request till api:et måste signeras på ett visst sätt, genom att konstruera ett "meddelande" och hasha den mot en privat nyckel som endast är tillgänglig för varje kund hos Coleo. Det hashade resultatet skickas tillsammans med en publik nyckel(kundens organisations-id) i Request Header:ns Authorization. För att göra det ännu säkrare måste varje Request vara tidsstämplad med tiden då Requesten görs. Varje meddelande är satt till att vara öppet i 3 minuter 12

18 räknat från tidsstämpeln i Requesten. På så sätt skyddar man sig bättre mot intrång då det tar längre tid än 3 minuter för att lista ut den privata nyckeln. Om man vill läsa på om hur det fungerar rent tekniskt kan man läsa dokumentationen till api:et. 13

19 5. Slutsats För samtliga i gruppen var det en ny erfarenhet att jobba i ett skarpt projekt i grupp mot en kund. Vi har haft en väldig fördel att få jobba mot en kund som har varit engagerad och kontaktbar i princip när som helst. Då Marcus på Coleo är utvecklare har man enkelt kunna ställa tekniska frågor och fått konkreta svar. De har också haft önskemål på hur de vill ha det rent tekniskt. Nackdelen med detta är att vi kanske inte fått den erfarenhet av att hantera kunder med låg eller ingen teknisk kompetens som egentligen inte vet vad de vill ha, så kallade jobbiga kunder. Vi är väldigt nöjda med resultatet av projektet. Vi har levererat ett Web Api som uppfyllde kraven, vi har till och med hunnit implementera mer än vad som var sagt från början. Vi har även lyckats få till en säker produkt, då det kan handla om känslig data som inte får komma i orätta händer. Det innebär lite mer jobb för användaren av api:et men som generar i en robust och säker produkt. För Coleos del kommer det även vara enkelt att utöka api:et med ny funktionalitet efter hand behoven växer. Arbetet i gruppen har även det fungerat bra, en del sjukdomar har stört, men det sådant man får räkna med. Då teknikerna vi har arbetat med varit mer eller mindre nya för alla i gruppen har mycket arbete skett tillsammans för att diskutera och ge förslag på hur man bäst löser ett problem. Att vi började med WCF och gick över till ASP.NET MVC 4 Web Api tacklade gruppen bra, alla var engagerade och läste in sig på nytt. Tidsplanen vi hade att utgå ifrån höll ganska väl. Som vi beskrivit leverade vi vad kunden efterfrågade och kunden var nöjd. Att tidplanen höll beror till stor del på gruppens engangemang att vilja leverera en bra produkt, ganska bra uppskattning på hur lång tid de olika uppgifterna skulle ta. Att byta språk/ramverk mitt i projektet kan man tänka sig att tidsplanen borde spricka. Men den korta inlärningskurvan och smidigheten med det nya ramverket gjorde snarare att implementeringen gick mycket snabbare och timmarna som spenderades på att studera in det nya ramverket åts upp ganska snabbt. För att läsa lite negativt som hänt under projektet, tittar under punk 8. Förslag till förbättringar inför kommande projekt. 14

20 6. Förslag på vidareutveckling Utöka antalet resurser som tillhandahålls av APIet Förbättra och utöka dokumentationen med exempelkod som visar hur man programmerar mot apiet Då autentiseringen är en ganska avancerad procedur kunna tillhandahålla ett plugin i de vanligaste programmeringsspråken för att underlätta. (Nu finns ett till ASP.NET) 15

21 7. Övertagande av organisation Coleo kommer att ta över utvecklingen och administrationen av Web Api:et. 16

22 8. Förslag till förbättringar inför kommande projekt Fortsätta med handledarmöten under hela projektet. Mer strukturerade möten, gå igenom sprinten mer noga och se vad som verkligen behöver läggas krut på. En bättre versionshantering på koden. Med SVN strulade det och det blev konflikter filer emellan hela tiden. En lösning skulle kunna vara Bitbucket och TortoiseHg vilket vi under slutet av projektet kikade lite snabbt på och det verkade onekligen smidigt för denna typ av projekt. Underhålla dokument än mer än vad vi gjort, ibland är det enkelt att implementera nya saker som dyker upp utan att underhålla dokumenten det berör. Vilket kan ställa till problem när man går igenom dem och ser att man gjort det man ska. Vid senare projekt är man kanske mer insatt i de tekniker man jobbar med, vilket skulle kunna leda till att man skulle kunna dela upp arbetet på ett effektivare sätt. Ibland satt vi 4 personer och gjorde samma sak, men som sagt, det var en del nya tekniker vi var tvungna att lära oss. 17