Webbteknik II, 1DV449 Laboration 2 RESTful webb-api Author: John Häggerud & Johan Leitet Semester: HT 2011 Course code: 1DV449
Inledning I denna laboration är det tänkt att Du ska skriva ett eget webb-api som stödjer sig på idéerna kring REST (Representational state transfer). Tanken är att detta API ska du sedan använda i kommande laboration och skriva en javascript-klient till. Genomförande Du ska vara beredd att själv kunna söka upp viss information för att lösa laborationen. Laborationen löses individuellt men diskutera gärna eventuella problem och lösningar med dina kurskamrater. Du ska kunna svara på frågor från laborationshandledaren rörande dina lösningar. Du ska kunna motivera dina lösningar vid redovisning. 2 (7)
Uppgiften Digitala tjänstemarknader är ett projekt som drivits här på Linnéuniversitetet. Projektet arbetade med lokala matproducenter och försökte hitta digitala lösningar för att sprida producenternas information och underlätta deras kommunikation med olika typer av parter. Som en del i detta projekt har ett webb-api utvecklats (främst av tidigare studenter inom webbprogrammeringsprogrammet) som via XML och JSON ger utvecklare tillgång till data om producenter och produkter. API:et är framtaget mer som en demonstrator än som en färdig produkt. Dock bör API:et räcka för våra behov i denna och framförallt kommande laboration. Den, ganska sparsmakade, dokumentationen för detta API finns att beskåda på http://api.matmarknad.se/doc Huvuddelen i denna uppgift är att skriva ett eget API med information om producenternas lokalisering/position (longitud och latitud), alltså information om vart dessa producenter bedriver sin verksamhet. Det kommer också ges en textfil med information om producenter och deras position som kan användas för att fylla det API Du skriver med data. Nedanstående bild beskriver strukturen över de olika delarna samt förhållande mellan laboration 2 och 3: 3 (7)
Befintligt Webb- API api.matmarknad.se Data mysql Laboration 2 RESTfull API Data om producenters position SQLite3 GET /producer o.s.v. GET /position POST /position PUT /position DELETE /position Laboration 3 Webbaserad klient (mobilanpassad) Uppgiften Denna uppgiften består alltså i att skriva ett API med data om producenters positionering. Varje producent har ett unikt id (se i API:et från matmarknad.se) som Du ska koppla ihop med en viss position. För att spara denna information används den enkla databashanteraren SQLite3 (http://www.sqlite.org/). 4 (7)
Informationen som ska sparas i en tabell är: producerid id-nummer för en producent. Detta ska alltså överstämma med producentens id som redan finns i matmarknads API (pid). longitude Longituden för aktuella producent. latitude Latituden för aktuell producent. description Beskrivning av platsen (förslagsvis producentens namn eller liknande). Till er hjälp får ni en textfil som innehåller ett antal rader med information om detta. En uppgift är alltså vara att överföra det som står i textfilen till er skapade databas-tabell. Textfilen består av 74 rader uppdelad på formen: latitud, longitud, producentens id (matchar mot matmarknad API:et), producentens namn Be RESTful Du ska alltså skriva ett webb-api mot den ovan beskrivna databasen som följer principerna för REST. Du ska skapa möjlighet för: Läsa ut alla producenters position Läsa ut en speciell producents position, via det unika id-numret Skapa en ny position Uppdatera en befintlig position Ta bort en producents position Tänk igenom hur http-protokollets egenskaper kan hjälpa dig med metodanrop, returkoder o.s.v. Du behöver inte fundera på inloggning och annat i denna uppgift. Naturligtvis bör man aldrig lägga uppdateringar, skapande och borttagning helt öppet! API:et ska returnera antingen XML eller JSON. Dock extra plus till de som gör en lösning där man som klient till API:et kan själv bestämma om man vill ha JSON eller XML, det vill säga att det finns stöd för båda dataformaten. 5 (7)
Du ska också dokumentera upp ditt API på ett bra sätt (webbaserad visning). Här kan följande artikel studeras för lite tankar kring detta: http://www.prestwoodboards.com/aspsuite/kb/document_view.asp?qid=1021 47 Krav på vad som ska göras för godkänd på laborationen - Skapa ett webb-api som stödjer sig i möjligaste mån på de principer som diskuterats i samband med REST. - Datalagringen för positioneringen ska sparas i en SQLite3. - Databasen ska fyllas med den information som man får i textfilen. - API:et ska kunna visa alla producenters position (id, longitude, latitude, description). - API:et ska kunna visa en efterfrågad producents (via producentens id) position. - API:et ska ge möjlighet att lägga till nya positioner (rader i databasen). - API:et ska ge möjlighet att uppdatera en befintlig position. - API:et ska ge möjlighet att ta bort en befintlig position. - API:et ska dokumenteras på ett lättförståeligt och överskådligt sätt. - API:et ska ge vettiga felkoder vid felaktiga anrop - API:et ska minst returnera XML alternativt JSON. Extra plus ifall det stödjer båda formaten och kan låta användaren (RESTful way) styra vilket dataformat som ska returneras. Tips - Naturligtvis måste du testa din kod/ditt API. Detta görs kanske enklast genom att skapa en simpel klient via JavaScript. Detta behövs också för att kunna redovisa uppgiften. 6 (7)
- Tänk igenom uppgiften innan du börjar koda. Läs på!!! Hur ska data returneras? Hur ska anropen se ut? Vilka parametrar ska tillåtas? Hur ska felhantering ske? 7 (7)