Planlegging / Kravspesifikasjon

Som i de fleste utviklingsprosjekt er det lurt å planlegge før vi begynner å kode. Vi begynner med å dele inn oppgavene i fire steg som må kartlegges:

1. Kravspesifikasjon. Som i alle prosjekter må kartlegge krav / begrensinger på det vi skal lage.
2. Hvilken ressurser, kan sammenlignes med å kartlegge objekter i OOP.
3. Hvordan representere ressurser. F.eks hvordan skal vi utveklse data mellom klient og server? XML, JSON, HTML eller annet.
4. Definere URIer som skal brukes. Når ressurser er på plass må vi definere APIet vårt sånn at vi kan bruke ressursene våre.

PS! Punkt 2, 3 og 4 inneholder terminologi som jeg skrev litt om i "En introduksjon til REST". Om du ikke har lest denne artikkelen enda, anbefaler jeg at du gjør det nå.

1 - Kravspesifikasjon

I denne artikkelen tenkte jeg at vi skulle designe en miniblogg bygd opp etter twitter modellen. Vi kan da tenke oss følgende scenarier:

• En bruker registrerer seg med brukernavn / passord. Brukeren lager altså en konto.
• Registrerte bruker poster på bloggen / skriver et innlegg. Vi skal begrense innleggets lengde til 140 tegn.
• Registrerte og uregistrerte brukere kan lese innleggene.
• Registrerte og uregistrerte brukere kan se brukerprofiler.
• Registrerte brukere kan oppdatere sine brukerprofiler (endre passord for eksempel).
• Registrerte og uregistrerte brukere kan søke i poster som er skrevet på bloggen.

Selv om dette ikke var så mange punkter utgjør det essensen i de fleste blogger, og er nok til vårt lille eksempel. Dette var altså punkt 1, kravspesifikasjonen vår.

2 - Kartlegge ressurser

Neste punkt på listen er å kartlegge / definere hvilken ressurser vi trenger. Utifra kravspesifikasjonen kan vi dra ut følgende:

• Bruker
• Liste av brukere
• Poster
• Liste av poster

Dette var altså punkt 2, ressurser på listen vi laget i starten.

3 - Kartlegge representasjoner

Som jeg skrev i "En introduksjon til REST" er en representasjon hvordan en ressurs ser ut på det tidspunktet den blir etterspurt. Representasjonen overføres ved hjelp av HTML og kan være hvilken som helst type binærstrøm. Men vi bør prøve å velge en representasjon som det finnes bred støtte for å lese på klientsiden, f.eks XML eller JSON. Denne gangen velger XML siden dette er et format som er utbredt, legg å lese og har god støtte iform av bibliotek på flere plattformer.

Vi kan da se for oss følgende måte å representere ressursene våre på.

Og tilsvarende for en bloggpost

4 - Definere URIer

Dette er et viktig punkt, spesielt om vi ønsker å lage en tjeneste som også andre skal kunne bruke. Det er nå vi definerer selve APIet, og det er viktig at gjør gode valg i dette steget. En god API bør ha URIer som er unike og ikke endrer seg.

Vi må også huske på at vi utvikler en nettjeneste, og ikke en nettside. Vi eller andre kan så i neste omgang bruke nettjenesten for å implementere funksjoner på en nettside. Nettjenesten vår skal i utgangspunktet brukes av datamaskiner og bør være tilpasset dette. Vi kan skille nettjenesten vår fra nettsiden ved å ha f.eks www.api.domeneavn.no (for APIet) og www.domeneavn.no (for hjemmeside).

For vår RESTful blog kan følgende være et godt forslag til URI oppsett:

• GET http://localhost:8080/brukere <--- GET - returnerer alle brukerene.

• GET / PUT / DELETE http://localhost:8080/brukere/{brukernavn} <--- GET - returnerer en bruker, PUT - redigerer en bruker, DELETE - sletter en bruker

• GET / POST http://localhost:8080/poster <--- GET - returnerer alle poster, POST - lager en ny post basert på XML data som ligger ved

• GET / DELETE http://localhost:8080/poster/{postID} <--- GET - returnerer posten, DELETE - sletter posten

• GET http://localhost:8080/poster/brukere/{brukernavn} <--- GET - returnerer alle poster som en bruker har lagt inn

Som du ser i listen over kan samme URIen brukes til å utføre forskjellige operasjoner på representasjonen. Typen bestemmer logikken som skal utføres på representasjonen, f.eks DELETE for å slette en representasjonen, og PUT for å opprette / redigere.

Det å koke opp forslag til URI design er ingen eksakt vitenskap, men noe som man må tilpasse til hvert enkelt tilfelleselve i.

Her kan du lese litt mer om URIer generelt: http://www.w3.org/Provider/Style/URI , og her kan du lese litt om RESTfule URIer spesifikkt: http://redrata.com/restful-uri-design/

Konklusjon

Designprosessen i et så enkelt eksempel som vi har brukt her er oversiktlig, og fokusert på ressurser. Vi kan bruke samme fremgangsmåter i et RESTful prosjekt som et vanlig nettsted prosjekt.

Det neste logiske steget er nå selve implementasjonen. Vi har et design / spesifikasjon og må etterhvert velge hvordan vi skal gjøre implementeringen rent teknisk. Vi har flere mulige Java RESTfulle rammeverk som kan være aktuelle, f.eks Jersey JAX-RS (referanse implementasjonen av Java API for RESTful Web Services Specifications), Restlet framework, JBoss RESTEasy JAX-RS og Struts 2 m/REST plugin.

Dette vil bli et tema for en ny artikkel senere.