Giters

jenslokken / api-workshop

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Velkommen til API-workshop! 🤓

Emoji-guide

Du kommer til å se noen emojis i oppgavene. De betyr ca det her:

  • 🏆 Oppgave: Her er hva du skal gjøre
  • 💡 Tips: Litt ekstra info som kan være greit å lære for å løse en oppgave
  • 🚨 Løsningsforslag: Her finner du en komplett gjennomgang av hvordan du kan løse oppgaven
  • 🧠 Dypdykk: Lenker og tips til hva man kan lese mer om for å få en dypere forståelse.

DEL 1

I denne delen skal vi lære oss å konstruere requester og bruke disse for å hente ut data fra et åpent API som eies av Digitaliseringsdirektoratet ved hjelp av verktøyet Postman.

Oppsett

Dersom du ikke allerede har lastet ned Postman, gjør det nå: https://www.postman.com/downloads/. Det er alt du trenger til denne delen!

Oppgaver

Oppgave 1

Vi starter veldig enkelt og skal bare hente ut restaurantene i listen fra https://smilefjes.herokuapp.com/tilsyn. Dokumentasjonen på dette finner du på https://smilefjes.herokuapp.com/api-docs/.

Ta en titt på all dataen du får ut. Denne skal vi i senere oppgaver vise i vår egen tjeneste 💥

🚨 Løsningsforslag Pass på at du gjør en GET-request og legg inn URLen under 
https://smilefjes.herokuapp.com/tilsyn

Oppgave 2

Nå skal vi ikke hente ut alle de 100 første restaurantene. I stedet skal vi hente ut alle restauranter som oppfyller et krav. Forslaget vårt er å velge et postnummer, f. eks. 7030 i Trondheim. Får du det til med en variabel må du gjerne legge til flere.

💡 Tips Vi må huske på å ha med `?` før våre parametere
🚨 Løsningsforslag Bytt ut URLen i oppgave 1 med den under: 
https://smilefjes.herokuapp.com/tilsyn?postnummer=7030

Konklusjon

Godt jobbet! Nå er du ferdig med del 1 og har lært deg å gjøre enkle kall til et åpent API 💯

DEL 2

I denne delen skal vi ta det et hakk videre. Nå skal vi se på hvordan vi kan konsumere data fra et eksisterende API inn vår egen frontend-applikasjon. Vi skal jobbe med en nesten ferdig frontend applikasjon. Applikasjonen lar brukerne se data om mattilsynets tilsyn på spisesteder i Oslo, Bergen og Trondheim. Det som gjenstår på applikasjonen er å koble den opp mot API'et vi brukte i første oppgave.

Oppsett

Om du ikke har gjort det allerede må du klone dette repoet før vi starter.

Om du ikke har jobbet med git og github kan du lese mer om git, og hvordan man kloner repoer fra GitHub. Om du bare vil komme i gang kan Github Desktop være en fin løsning.

Når du har fått klonet repoet åpner du det i en egnet editor. Om du ikke har en installert en fra før er Visual Studio Code en av de mest populære.

Åpne en terminal og naviger til rotmappen av repoet. Her må du kjøre to kommandoer for å få applikasjonen til å starte. Først må vi laste ned alle pakker applikasjonen trenger for å starte. Dette gjøres ved å kjøre denne kommandoen:

npm install

Deretter skal vi starte opp applikasjonen med:

npm run start

Når applikasjonen starter skal nettleseren din automatisk åpnes med applikasjonen. Om den ikke gjør det kan du gå inn på nettadressen http://localhost:3000/.

Oppgaver

Når du trykker på "Hent tilsyn" i appen skjer det ingenting. Dette er fordi vi må koble sammen frontend med backend 🤓 Oppgaveteksten til hver oppgave finner du i oppgavefilene. Vi skal bruke API'et fra del 1. Dokumentasjonen på dette finner du på https://smilefjes.herokuapp.com/api-docs/.

Oppgave 1

Her skal vi få applikasjonen til å hente og vise frem en liste med tilsyn. I del 1 av workshoppen brukte du postman til å hente ut en hel liste med tilsyn. Finn frem URL'en du brukte for å hente listen og bytt ut innholdet i url-variablen.

Om du finner riktig url kommer applikasjonen til å vise frem en liste med tilbud når du trykker på knappen "Hent tilsyn"

Finn filen oppgave1.ts. Her skal vi gjøre applikasjonen i stand til å hente en liste med tilsyn.

🚨 Løsningsforslag Bytt ut innholdet i url-variablen til dette: 
const url = "https://smilefjes.herokuapp.com/tilsyn";

Når du har fått løst oppgaven skal appen vise en liste med tilsyn. Det betyr at vi har klart å koble sammen vår frontend-applikasjon med et eksternt API. Nå henter vi ut alle tilsyn. I neste oppgave skal vi se på hvordan vi kan hente ut kun de tilsynene vi er interessert i.

🧠 Dypdykk Om du så litt etter la du merke til at vi brukte `fetch()` til å hente data. Om du har lyst til å lage flere webapplikasjoner som henter data fra web kommer du garantert til å ha nytte av å kunne mer om dette. MDN har en fin guide: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API. 
fetch("http://example.com/movies.json")
  .then((response) => response.json())
  .then((data) => console.log(data));

Oppgave 2

Her skal vi få applikasjonen til å hente ut et subsett av alle tilsyn basert på hvilke parametre vi legger ved i spørringen. Det ble nevnt query-parametre i et av foredragene. Nå skal vi benytte oss av disse.

Start med å endre verdien av variablen shouldUseInputFields fra false til true. Sjekk forsiden av appen. Endret denne seg nå?

Det skal ha dukket opp noen nye inputfelter, men det som også dessverre har skjedd er at "Hent tilsyn" ikke lenger fungerer. Det skal vi nå fikse, og på en bedre måte enn det vi gjorde i oppgave 1.

Vi skal nå konstruere en ny url som også tar i bruke queryparams. URL'en vi trenger for å løse oppgave 2 blir på følgende format:

'URL FRA OPPGAVE 1' + 'QUERYPARAMETRE'

Om du står fast kan du sjekke "💡Tips"

Finn filen oppgave2.ts. Her skal vi gjøre applikasjonen i stand til å hente ut kun de tilsynene vi har lyst på ved å bruke query-parametere, også kjent som query params.

💡 Tips

Query params

Husk at query params legges til på slutten av URLen på følgende format: ?variabel1=verdiPåVariabel1&variabel2=verdiPåvariabel2.

En hel URL vil da bli seende ut som dette:

"http://example.com/movies?year=2021&genre=thriller";

String/tekststreng i JavaScript

Det finnes mange måter å håndtere tekststrenger med variabler i JavaScript. Den letteste er kanskje å bare plusse alle de ulike strengene sammen på denne måten:

const year = "2021";
const genre = "thriller";

const url =
  "http://example.com/movies?" + "year=" + year + "&" + "genre=" + genre;

Men JavaScript har også noe som heter template literals. Dette pleier ofte å bli ganske mye lettere å lese når det blir flere variabler. Her er akkurat samme tekststreng ved bruk template literals. Legg merke til bruk av backtikcs: `

const year = "2021";
const genre = "thriller";

const url = `http://example.com/movies?year=${year}&genre=${genre}`;
🚨 Løsningsforslag Bytt ut innholdet i url-variablen til dette: 
const url = `https://smilefjes.herokuapp.com/tilsyn?postnummer=${postnummer}&poststed=${poststed}&smilefjes=${smilefjes}`;

Når du har fått løst oppgave 2 har vi laget muligheten til å hente ut en liste med tilsyn basert på de ulike parameterne vi sender inn. Du kan verifisere at du har fått til oppgaven ved å sette Trondheim som poststed og nøytral som smilefjes. Om du har fått løst oppgaven skal listen nå kun inneholde restauranter med nøytralt smilefjes.

🧠 Dypdykk Du kan gjøre ganske mye kult med template literals. Ta en titt [her](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) for flere eksempler.

Oppgave 3

Nå har vi gjort applikasjonen i stand til ikke bare å hente tilsyn, men også hente de tilsynene vi har lyst på basert på query-parameterne vi sender inn. Nå skal vi se på hvordan vi kan gå frem for å hente ut detaljer om et tilsyn.

Start med å endre verdien av variablen enableDetailsLink fra false til true. Nå skal det dukke opp en knapp med "Se detaljer" på hvert tilsyn i listen. Denne knappen tar deg videre til en detaljeside for hvert tilsyn.

Du skal nå bytte url slik at applikasjonen er i stand til å hente data for å fylle ut data om den nye siden. Om du står fast kan du sjekke "💡Tips"

💡 Tips For å løse oppgaven må du ta i bruke et stiparameter (path-params). Stiparametre brukes ofte ved at man sender inn id'en til ressursen man har lyst til å hente. Sti parametre legges til på slutten av stien på følgende format: `/stiParameter`.

En hel URL vil da bli seende ut som dette:

"http://example.com/movie/123";
🚨 Løsningsforslag Bytt ut innholdet i url-variablen til dette: 
const url = `https://smilefjes.herokuapp.com/tilsyn/${tilsynId}`;

Oppgave 4

Nå har vi gjort applikasjonen i stand til å hente en liste med tilsyn, samt vise detaljer om et enkelt tilsyn. Problemet er at vi enda ikke får hentet ut de tilsynene som har resultert i et surt smilefjes. Om vi prøver å hente disse får vi bare en tom liste tilbake. Dette skal vi løse ved å bruke header-parametre.

Start med å endre verdien av variablen shouldUseAccessToken fra false til true

Vi skal bruke nøyaktig samme url som i oppgave 2, men også legge til det nye parameteret i headeren.

Om du står fast kan du sjekke "💡Tips"

💡 Tips For å løse oppgaven må du ta i bruke et header-paramtre og sende inn det superduperhemmeligepassordet der. MDN har en fin beskrivelse av hva HTTP-headeren er for noe her: https://developer.mozilla.org/en-US/docs/Glossary/Request_header.

I frontendapplikasjonen vår bruker vi Fetch til å hente data fra backenden. I tillegg til selve URL'en kan vi også sende inn et javascript-objekt inn som parameter til fetch. Du kan se dokumentasjon og eksempeler på det på https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options.

I eksempelet under bruker vi en header-parameter for å styre hvilket format vi ønsker å få data tilbake fra backend.

return fetch(url, {
  headers: {
    "Content-Type": "application/json",
  },
});
🚨 Løsningsforslag 
return fetch(url, {
  headers: {
    accessToken: "superduperhemmeligpassord",
  },
});

Konklusjon

Gratulerer! 🎉 Du har nå fått koblet sammen frontend med et eksisterende API, og er nå ferdig med del to av workshopen.

DEL 3

I del 3 skal vi se på hvordan en backend kan fungere. Vi kommer til å kjøre vår egen backend lokalt på maskinen.

Oppgaver

På samme måte som i del 2 må vi laste ned, installere og kjøre opp backend. Kildekoden til backend finner du på https://github.com/bekk/api-workshop-backend.

Klon repoet og installer programvaren på samme måte som i del 2. Husk å bytt URL!

Etter at prosjektet er lastet ned, naviger til backend-mappen og kjør "npm install" for å installere programvaren, og "npm run dev" for å starte backend.

npm install
npm run dev

Når man kjører "npm run dev" vil backend vil starte opp lokalt på http://localhost:3003 Verifisert at backend kjører ved å se at meldingen "Cannot GET /" dukker opp når du åpner http://localhost:3003 i nettleseren.

Oppgave 1

I del 1 brukte vi Postman for å kjøre requests mot en tjeneste ute på internett. Nå skal vi bruke bruke postman for å hente data fra vår backend som kjører lokalt på maskinen. Bytt ut URL fra del 1 til å gå mot vår lokale backend.

💡 Tips Husk at vår lokale backend kjører på http og ikke https.
🚨 Løsningsforslag Sett endepunkt-URL i postman til å være: http://localhost:3003/tilsyn

Oppgave 2

Bytt ut endepunktene i frontend-løsningen til å gå mot den lokale backend-tjenesten.

🚨 Løsningsforslag

I filen oppgave1.ts i frontend-prosjektet sett url-variabelen til å være:

const url = "http://localhost:3003/tilsyn";

I filen oppgave2.ts i frontend-prosjektet sett url-variabelen til å være:

const url = `http://localhost:3003/tilsyn?postnummer=${postnummer}&poststed=${poststed}&smilefjes=${smilefjes}`;

I filen oppgave3.ts i frontend-prosjektet sett url-variabelen til å være:

const url = `http://localhost:3003/tilsyn/${tilsynId}`;

For å teste at endringene fungerer må både frontenden og backenden kjøre. Etter vi har startet både frontend og backend kan vi gå til http://localhost:3000 for å sjekke at ting fungerer som før.

Oppgave 3

Lag et nytt endepunkt i backend /hei som returnerer "hei". Verifiser at det fungerer med å bruke postman.

🧠 Dypdykk

Det finnes veldig mange forskjellige språk og teknologier man kan bruke for å lage en backend. I denne workshopen har vi brukt node express som rammeverk og javascript som programmeringsspråk. Du kan lese mer om node express her.

I dette endepunktet returnerer vi en tekst, mens vanligvis for API som gir data som skal vises på en nettside blir dataformat JSON brukt.

🚨 Løsningsforslag

I app.js filen legg til:

app.get("/hei", (req, res) => {
  res.send("hei");
});

og test endepunktet med postman mot http://localhost:3003/hei og sjekk at reponsen er "hei". Hvis ting fungerer som før har vi akkurat koblet sammen frontend og backend som begge kjører lokalt på maskinen!

Oppgave 4 (bonus)

Lag et endepunkt som gir tilbake et smilefjes :), / :|, :( basert på tilsyns-id /tilsyn/{tilsynsId}/fjes. Test det med postman.

💡 Tips

Hvis du sitter fast kan det være en god idé å kopiere endepunktet til tilsynsId og endre det.

Du finner tre statuskoder i smilefjes-feltet til et tilsyn: BLID, NØYTRAL og SUR

🚨 Løsningsforslag

I app.js filen legg til:

app.get("/tilsyn/:tilsynsId/fjes", (req, res) => {
  const tilsyn = tilsynsListe.find((tilsyn) => {
    return tilsyn.tilsynsId.toString() == req.params.tilsynsId;
  });

  let fjes;
  if (tilsyn.smilefjes === "BLID") {
    fjes = ":)";
  } else if (tilsyn.smilefjes === "NØYTRAL") {
    fjes = ":|";
  } else {
    fjes = ":(";
  }

  res.send(fjes);
});

og test endepunktet med postman mot http://localhost:3003/tilsyn/935d9947-2304-4e72-a57c-7f9f03081a1d/fjes

Oppgave 5 (bonus)

En restaurant kan ha hatt flere tilsyn. Lag et endepunkt som returnerer en liste med alle tilsyn for en restaurant. Dette endepunktet kan for eksempel ta inn navnet på restaurant. For å teste om løsningen fungerer kan man bruke bedriftsnavnet Savanna eller Nam Nam, begge har flere tilsyn.

💡 Tips

Her kan det også være greit å ta utagangspunktet i endepunktet til tilsynsId.

I endepunktet til tilsyn er vi kun interessert i å finne ett resultat, og vi bruker derfor find, en annen funksjon som kan brukes til å finne alle resultatene fra en liste er filter. Sjekk filter dokumentasjonen for eksempler på bruk.

🚨 Løsningsforslag

I app.js filen legg til det under, og test at det fungerer med å sjekke http://localhost:3003/tilsyn/resturant/Savanna

app.get("/tilsyn/resturant/:navn", (req, res) => {
  const alleTilsyn = tilsynsListe.filter((tilsyn) => {
        return tilsyn.navn === req.params.navn;
  });

  res.send(alleTilsyn);
});

About

Languages

Language:TypeScript 88.1%Language:HTML 11.9%