jomartinsl / smarthouseprojectc

ING301 prosjekt - Del C

I del C av prosjektet skal dere implementere en REST API for en smarthus sky-tjeneste ved bruk av rammeverket FastAPI.

Setup og Startup

Start-koden for prosjektet finnes i dette GitHub repository:

https://github.com/selabhvl/ing301-projectpartC-startcode.git

Igjen forutsettes at dere har implementert en fullstendig løsning til forrige oppgaven (del B). Enten kan dere bygge direkte på deres eksisterende løsning eller dere begynner med et helt fersk repository ved å klone startkoden for første delen igjen også kopiere filene til henholdsvis løsningsforslagene A og B inn for å ha et utgangspunkt til denne oppgaven.

Dere kopierer inn filene fra dette repository'et ("Download as ZIP") inn i det eksisterende prosjekt slik at mappestrukturen skal se noenlunde slik ut:

.
├── data
│  └── db.sql
├── README.md               <-- erstatt hvis du vil
├── smarthouse
│  ├── __init__.py
│  ├── api.py               <-- nytt
│  ├── domain.py
│  └── persistence.py
├── tests
│  ├── __init__.py
│  ├── bruno                <-- nytt
│  │  └── ...
│  ├── demo_house.py
│  ├── test_part_a.py
│  └── test_part_b.py
└── www                     <-- nytt
   └── ...

Selv om det er mulig (og at dette vil være en veldig lærrik oppgave) å implementere en HTTP-server helt fra bunn av, så ville dette være veldig tidkrevende også. Vi skal derfor bruke en bibliotek som heter FastAPI. FastAPI er ikke en del Python sin standard bibliotek og må derfor installeres som en Python Packages. Installasjon av packages kan være en utfordring siden man må manøvrere ting som Externally Managed Environments, "package managers" som pip, conda, poetry osv... Dette kan være utfordrende i starten!

En god praksis er å lage noe som kalles en virtual environment for hver Python prosjekt. Dette gjør at man kan styre hvilken Python-fortolker som skal brukes og for å kunne holde paketer adskilt.

For å oprette en slik virtual environment åpner du et nytt terminalvindu og så beveger du deg inn i prosjektmappen. Her utfører du følgende kommando:

py -m venv .venv

hvis du bruker Windows, eller

python3 -m venv .venv

hvis du bruker Linux/UNIX/MacOS.

Vær også obs på at under noen operativsystemer må venv-modulen installeres for første gang gjennom operativsystemets pakkeforvaltning, f.eks. under Ubuntu må du utføre:

sudo apt-get install python3-venv

Etter at det virtuelle Python miljøet er blitt opprettet må det aktiveres med

.venv\Scripts\activate

under Windows, eller

source .venv/bin/activate

under Linux/UNIX/MacOS.

Du vil nå se at ledeteksten i konsollen har forandret seg litt og hvis du nå sjekker hvilke python og pip er som aktive:

Windows:

where python 
where pip

Linux/UNIX/MacOS

which python 
which pip

Da vil du se at disse nå peker mot den .venv-mappen som ble opprettet før.

Nå at det virtuelle Python miljø er på plass er det lurt å sjekke om pip der og oppdatert:

python -m pip install --upgrade pip

Istedenfor python -m pip burde du også kunne skrive bare pip. Hvis du får en feilmelding at modulen pip kan ikke finnes så må du eventuelt sjekke om denne pakken må installeres gjennom operativsystemets forvaltningssystem (noe som heter python3-pip).

Når pip er på plass kan FastAPI samt avhengigheter installeres ved å kjøre følgende kommandoer:

python -m pip install fastapi 
python -m pip install "uvicorn[standard]"

Nå skulle alt være på plass for å kunne kjøre applikasjonen:

python -m uvicorn smarthouse.api:app --reload

når konsollen viser noe slik:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [28720]
INFO:     Started server process [28722]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

så er web applikasjonen klart! Du kan åpner nettleseren på

http://127.0.0.1:8000

for å se en liten demoside og

http://127.0.0.1:8000/docs

vil gi deg en oversikt over REST ressursene som finnes.

Hvis du ikke allerede har gjort det, så er det nå en god tidspunkt å laste ned Bruno, starte det, lage en ny "collection" og prøve å sende en HTTP GET request til http:127.0.0.1:8000/hello.

Gratulerer! Da er Setup avsluttet og du er klar til å begynne med oppgaven!

Noen ord vedrørende virtuelle Python miljø

Enn så lenge du holder konsollen åpen så vil være web-tjeneren være aktivt. I tillegg vil den automatisk reagere på alle endringer i koden og automatisk oppdatere seg slik at du får en nesten sømløs opplevelse. Når du vil likevel avslutte applikasjonen må du sette fokus på terminalvinduet også trykker du Ctrl + C samtidig, da kommer du tilbake til ledeteksten.

Hvis du vil gå ut av det virtuelle Python miljøet (f.eks. for å jobbe med et annen Python projsket) kan du kalle:

deactivate

For å komme inn i det virtuelle miljøet igjen gjør du akkurat likt som beskrevet ovenfor ved å kalle activate. Husk at dette også må gjøres når du starter PCen din på nytt eller du åpner et nytt terminalvindu.

I tillegg vil du kanskje også at din editor eller IDE samarbeider med det virtuelle miljøet. Sjekk dokumentasjonen til VS Code eller PyCharm. I de fleste tilfellene vil disse automatisk oppdager at det finnes en venv i ditt prosjekt og forholder seg tilsvarende.

Oppgavebeskrivelse

Som nevnt består altså oppgaven i det å lage en REST API for smarthuset. Konkret skal dere opprette følgende endepunkter:

Det skal finnes endepunkter får inspisere strukturen til huset:

• GET smarthouse/ - information on the smart house
• GET smarthouse/floor - information on all floors
• GET smarthouse/floor/{fid} - information about a floor given by fid
• GET smarthouse/floor/{fid}/room - information about all rooms on a given floor fid
• GET smarthouse/floor/{fid}/room/{rid}- information about a specific room rid on a given floor fid

Det skal finnes endepunkter for tilgang til enheter:

• GET smarthouse/device - information on all devices
• GET smarthouse/device/{uuid} - information for a given device identfied by uuid

Det skal finnes spesielle endepunkter for tilgang til sensor funksjoner:

• GET smarthouse/sensor/{uuid}/current - get current sensor measurement for sensor uuid
• POST smarthouse/sensor/{uuid}/current - add measurement for sensor uuid
• GET smarthouse/sensor/{uuid}/values?limit=n - get n latest available measurements for sensor uuid. If query parameter not present, then all available measurements.
• DELETE smarthouse/sensor/{uuid}/oldest - delete oldest measurements for sensor uuid

Det skal finnes spesielle endepunkter for tilgang til aktuator funskjoner:

• GET smarthouse/actuator/{uuid}/current - get current state for actuator uuid
• PUT smarthouse/device/{uuid} - update current state for actuator uuid

For de fleste av endepunktenes funksjonalitet kan en mye av funksjonene i SmartHouse-klassen sannsynligvis gjenbrukes og noen steder kan det være relevant og koble seg mot databasen ved bruk av SmartHouseRepository. Muligens sistnevnte må utvides med funksjonalitet for å oppfylle alle kravene stil av endepunkt-spesifikasjonen ovenfor.

Warning

Når du i løpet av oppgaven skal legge til en database-forbindelse ved å bruke SmartHouseRepository kan det være at du løper i en feilmelding som

...
SQLite objects created in a thread can only be used in that same thread.

I dette tilfelle må du erstatte en linje i konstruktoren til SmartHouseRepository i persistence.py. Konkret må

def __init__(self, file: str) -> None:
    self.file = file
    self.conn = sqlite3.connect(file)

byttes ut mot

def __init__(self, file: str) -> None:
    self.file = file
    self.conn = sqlite3.connect(file, check_same_thread=False)

Husk at data som returneres fra endepunktet eller sendes til endepunktet skal være i JSON-formatet. FastAPI er i stand til å automatisk overføre Python objekter til JSON i tilfelle av innebygde Python verdier:

• strenger (str),
• tall (int, float),
• sannhetsverdier (bool),
• None-verdien,
• lister og ordbøker med streng-nøkler som igjen inneholder lister, ordbøker eller verdiene nevnt ovenfor.

Når du har definert din egen klass må du i utgangspunktet skrive din egen serialiserings-mekanisme. Men du kan også bruke Pydantic-biblioteket (den kommer automatisk med når man installerer FastAPI) for å oversette dine egne klasser automatisk.

Viktig er at dere på forhånd tar en avgjørelse om hvordan inn- og utdata for hver endepunkt skal være strukturert.

Testing

En del av oppgaven er å teste deres endepunkter. For dette anbefaler vi Bruno-verktøyet som gjør det mulig å lage en Collection av test-request og sjekker disse inn i git. Dette startkode repository inneholder en slik påbegynt "Test-Suite" som ligger under tests/bruno. Du kan åpne denne samlingen ved å trykke "Open Collection" når du starter Bruno på første gang eller hvis du allerede har lagt noen collections selv så trykker du på de tre prikkene oppe til høyre og velger "Open Collection" derifra. Det åpner seg en filutforsker-vindu der du kan navigere til den nevnte mappen i din filsystem. Her er det også demonstrert hvordan du kan bruker variable og hvordan man skrive tester i Bruno ved bruk av assertions (forventninger).

Tips og diverse

For å løse oppgaven kan det være en god idé å søke inspirasjon i eksemplet fra forelesningen i uke 12 der FastAPI ble brukt til å utvikle en REST API for sykkelcomputer eksemplet:

Koden finnes her:

https://github.com/selabhvl/ing301public/tree/main/examples/12_restapi_webservices

Det er også hjelp å hente i dokumentasjonen for FastAPI som finnes via:

https://fastapi.tiangolo.com

smarthouseprojectc's Issues

Feedback: Oppgave 6: Prosjekt Del C

Deres innsending viser et godt stykke arbeid med implementasjonen av REST API for smarthuset ved bruk av FastAPI. Det står tydelig at dere har lagt en innsats i å forstå kravene i oppgavebeskrivelsen og realisere disse gjennom kode. Nedenfor følger tilbakemelding på de forskjellige aspektene av arbeidet deres:

Det dere gjorde bra:

• API-implementasjon: Dere har gjort en god jobb med å implementere API-endepunktene som var oppgitt i oppgavebeskrivelsen. Dette gir et solid grunnlag for en fungerende webservice.
• Bruk av FastAPI: Måten dere har brukt FastAPI viser en forståelse for moderne webservice-utvikling. FastAPI er et kraftig verktøy, og dere har utnyttet det godt for å lage ryddige og lesbare API-endepunkter.
• Feilhåndtering og datainnhenting: Implementasjonen av å hente og vise informasjon, så vel som håndtering av tilfeller hvor enheter ikke finnes, er håndtert på en god måte. Dette forbedrer brukervennligheten og robustheten til API-et.

Potensielle feil eller begrensninger:

• Håndtering av indekser: Direkte indeksering i listen som returneres fra get_floors() kan føre til IndexError dersom fid ikke eksisterer i listen. En sikrere måte å håndtere det på ville vært å bruke en try/except blokk eller undersøke om indeksen finnes først.
• Tilkoblingshåndtering i databasen: Å bruke conn.cursor() direkte i API-endepunkter uten noen form for tilkoblingshåndtering (som context manager eller try/finally) kan lede til at tilkoblinger blir hengende åpne ved feil.

Forbedringsforslag for fremtiden:

• Pydantic-modeller: Vurder å definere og bruke Pydantic-modeller for inn- og utdataene til API-et. Dette kan bidra til økt kodekvalitet ved å tilby validering og dokumentasjon av datastrukturene som brukes på tvers av API-et.
• Automatisk generert dokumentasjon: Benytt deg av FastAPIs støtte for OpenAPI for å gi automatisk generert dokumentasjon av API-et, som kan gjøre det lettere for andre utviklere å ta i bruk tjenesten dere tilbyr.

Alt i alt har dere levert en solid løsning på oppgaven, og jeg oppfordrer dere til å fortsette å utforske mer avanserte aspekter ved webutvikling og FastAPI. Fortsett med det gode arbeidet!

Dere kan bare lukke dette "issue" som løst når dere har lest gjenomm den 😉