diff --git a/backend/backend-api.md b/backend/backend-api.md new file mode 100644 index 00000000..edb1e946 --- /dev/null +++ b/backend/backend-api.md @@ -0,0 +1,293 @@ +# Backend-API +## Queries +### game + +Henter informasjon om ett enkelt spill ved ID. + +```graphql +game(id: ID!): Game +``` + +#### Argumenter + +| Navn | Type | Default | Beskrivelse | +| ---- | ----- | ------- | --------------- | +| `id` | `ID!` | — | ID til spillet. | + +#### Returnerer + +[`Game`](#game-1). Returnerer `null` hvis spillet ikke finnes eller id-en er ugyldig. + +#### Eksempel + +```graphql +{ + game(id: "3498") { + name + esrbRating + genres { name } + } +} +``` + +```json +{ + "data": { + "game": { + "name": "Grand Theft Auto V", + "esrbRating": "Mature", + "genres": [{ "name": "Action" }] + } + } +} +``` + +--- + +### games + +Henter en side med spill, med valgfritt søk og filtre. Resultatet er sortert etter popularitet. + +```graphql +games(search: String, filter: GameFilter, first: Int = 20): GameConnection! +``` + +#### Argumenter + +| Navn | Type | Default | Beskrivelse | +| -------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------- | +| `search` | `String` | — | Søk i tittel og alternative navn. Skiller ikke mellom store og små bokstaver, og matcher deler av navnet. | +| `filter` | [`GameFilter`](#gamefilter) | — | Filtrering på sjanger, plattform og utgivelsesår. | +| `first` | `Int` | `20` | Antall spill på siden. Begrenset til 1–50. | + +Alle argumenter er valgfrie og kan kombineres. + +#### Returnerer + +[`GameConnection`](#gameconnection) med spillene på siden og totalt antall treff. + +#### Eksempel: søk + +```graphql +{ + games(search: "zelda", first: 3) { + totalCount + edges { node { name } } + } +} +``` + +```json +{ + "data": { + "games": { + "totalCount": 55, + "edges": [ + { "node": { "name": "The Legend of Zelda: Breath of the Wild" } }, + { "node": { "name": "The Legend of Zelda: Ocarina of Time" } }, + { "node": { "name": "The Legend of Zelda: Tears of the Kingdom" } } + ] + } + } +} +``` + +#### Eksempel: filtre + +Action- og RPG-spill på PC, utgitt 2015–2020: + +```graphql +{ + games( + filter: { genreIds: ["1", "14"], platformIds: ["9"], releasedFrom: 2015, releasedTo: 2020 } + first: 3 + ) { + totalCount + edges { node { name released } } + } +} +``` + +```json +{ + "data": { + "games": { + "totalCount": 2006, + "edges": [ + { "node": { "name": "The Witcher 3: Wild Hunt", "released": "2015-05-18" } }, + { "node": { "name": "Fallout 4", "released": "2015-11-09" } }, + { "node": { "name": "Cyberpunk 2077", "released": "2020-12-10" } } + ] + } + } +} +``` + +--- + +### genres + +Henter alle sjangre, sortert alfabetisk. + +```graphql +genres: [Facet!]! +``` + +#### Argumenter + +Ingen. + +#### Returnerer + +Liste med [`Facet`](#facet). + +#### Eksempel + +```graphql +{ + genres { id name } +} +``` + +```json +{ + "data": { + "genres": [ + { "id": "1", "name": "Action" }, + { "id": "2", "name": "Adventure" }, + { "id": "3", "name": "Arcade" } + ] + } +} +``` + +--- + +### platforms + +Henter alle plattformfamilier (PC, PlayStation, Xbox, …), sortert alfabetisk. + +```graphql +platforms: [Facet!]! +``` + +#### Argumenter + +Ingen. + +#### Returnerer + +Liste med [`Facet`](#facet). + +Merk: ID-ene her er plattformfamilier og er ikke de samme som ID-ene i `Game.platforms`, som er enkeltkonsoller. + +#### Eksempel + +```graphql +{ + platforms { id name } +} +``` + +```json +{ + "data": { + "platforms": [ + { "id": "9", "name": "PC" }, + { "id": "10", "name": "PlayStation" }, + { "id": "13", "name": "Xbox" } + ] + } +} +``` + +## Mutations +> Dette skal legges til når funksjonalitet for brukere blir lagt til + +## Types +### Game + +Et spill med detaljer og relasjoner. + +| Felt | Type | Beskrivelse | +| --------------------------- | ------------------- | ----------------------------------------------------------------- | +| `id` | `ID!` | ID til spillet. | +| `name` | `String!` | Tittel. | +| `description` | `String` | Beskrivelse i ren tekst. | +| `released` | `String` | Utgivelsesdato, `YYYY-MM-DD`. | +| `website` | `String` | Offisiell nettside. | +| `added` | `Int!` | Antall RAWG-brukere som har lagt spillet til i en liste. Brukes som mål på popularitet. | +| `metacritic` | `Int` | Metacritic-score, 0–100. | +| `esrbRating` | `String` | Amerikansk aldersgrense, f.eks. `Mature`. | +| `dominantColor` | `String` | Hovedfargen i forsidebildet som hex, f.eks. `0f0f0f`. | +| `backgroundImage` | `String` | URL til forsidebildet. | +| `backgroundImageAdditional` | `String` | URL til et ekstra bilde. | +| `screenshots` | `[String!]!` | URL-er til skjermbilder. Tom liste hvis ingen. | +| `genres` | [`[Facet!]!`](#facet) | Sjangre. | +| `platforms` | [`[Facet!]!`](#facet) | Enkeltkonsoller, f.eks. PlayStation 4. | +| `stores` | [`[Facet!]!`](#facet) | Butikker spillet selges i. | +| `developers` | [`[Facet!]!`](#facet) | Utviklere. | +| `publishers` | [`[Facet!]!`](#facet) | Utgivere. | +| `tags` | [`[Facet!]!`](#facet) | Tagger fra RAWG, f.eks. Open World. | + +Relasjonene returnerer en tom liste hvis spillet ikke har noen. + +--- + +### Facet + +Felles type for sjangre, plattformer, butikker, utviklere, utgivere og tagger. + +| Felt | Type | Beskrivelse | +| ------ | --------- | ----------- | +| `id` | `ID!` | ID. | +| `name` | `String!` | Navn. | + +--- + +### GameConnection + +Resultatet av [`games`](#games). Følger Relay-mønsteret for paginering (se [dokumentasjon](https://graphql.org/learn/pagination/)). + +| Felt | Type | Beskrivelse | +| ------------ | --------------------------- | --------------------------------------------------- | +| `edges` | [`[GameEdge!]!`](#gameedge) | Spillene på denne siden. | +| `pageInfo` | [`PageInfo!`](#pageinfo) | Informasjon for å hente neste side. | +| `totalCount` | `Int!` | Totalt antall spill som matcher søk og filtre. | + +--- + +### GameEdge + +Ett spill i en [`GameConnection`](#gameconnection). + +| Felt | Type | Beskrivelse | +| -------- | -------------------- | ------------------------------------ | +| `node` | [`Game!`](#game-1) | Spillet. | +| `cursor` | `String!` | Posisjonen til spillet i listen. | + +--- + +### PageInfo + +| Felt | Type | Beskrivelse | +| ------------- | ---------- | ------------------------------------------------------------- | +| `hasNextPage` | `Boolean!` | `true` hvis det finnes flere spill etter denne siden. | +| `endCursor` | `String` | Cursor til siste spill på siden. Sendes som `after` for neste side. | + +--- + +### GameFilter + +Input-type for filtrering i [`games`](#games). Alle felt er valgfrie. + +| Felt | Type | Beskrivelse | +| -------------- | -------- | ------------------------------------------------------------------------------ | +| `genreIds` | `[ID!]` | Spill som har **alle** de valgte sjangrene. ID-er fra [`genres`](#genres). | +| `platformIds` | `[ID!]` | Spill på **minst én** av de valgte plattformfamiliene. ID-er fra [`platforms`](#platforms). | +| `releasedFrom` | `Int` | Utgitt dette året eller senere, f.eks. `2015`. | +| `releasedTo` | `Int` | Utgitt dette året eller tidligere, f.eks. `2020`. | + +Merk: Spill uten utgivelsesdato utelates når `releasedFrom` eller `releasedTo` er satt. ID-er som ikke er tall ignoreres. + + diff --git a/db/.env.example b/db/.env.example deleted file mode 100644 index 2f4cadc4..00000000 --- a/db/.env.example +++ /dev/null @@ -1,4 +0,0 @@ -VM_USER=brukernavn -VM_HOST=it2810-02.idi.ntnu.no -TUNNEL_PORT=5433 -DATABASE_URL=postgresql://gameapp:PASSORD@localhost:5433/gamesdb diff --git a/db/.gitignore b/db/.gitignore deleted file mode 100644 index 4bed5da9..00000000 --- a/db/.gitignore +++ /dev/null @@ -1 +0,0 @@ -*.parquet diff --git a/db/database-connect.md b/db/database-connect.md index c701b6c4..22b178e7 100644 --- a/db/database-connect.md +++ b/db/database-connect.md @@ -1,23 +1,55 @@ +# Database-connect +## 1. Konfigurere `.env` +1. Koble til NTNU VPN hvis du er utenfor campus. +2. Kopier `backend/.env.example` til `backend/.env` +3. Fyll inn verdien til `VM_USER`, og `PASSORD` i `DATABASE_URL`. -#### Database-connect - -Scripts for å koble seg til database ligger i `/scripts`. +`backend/.env` skal se ut slik: +``` +# tunnel script env vars +VM_USER= +VM_HOST=it2810-02.idi.ntnu.no +TUNNEL_PORT=5433 + +# backend server env vars +DATABASE_URL=postgresql://webapp:@localhost:5433/gamesdb +PORT=3001 +JWT_TOKEN= +``` -###### db-tunnel.sh +## 2. Database-tilkobling under utvikling +#### Linux/Mac +Gå til rot i repo (dvs. `T02-Project-2` mappen) og kjør kommandoen: +```bash +pnpm db:tunnel +``` -Spesifikt inneholder denne `db-tunnel.sh` som oppretter en ssh tunnel til vm over porten `5432`. Dette gjør at all trafikk som normalt går til `localhost:5432` rutes til postgres på serveren, slik at vi slipper å laste ned hele databasen på hver av pc-ene våre. +La terminalen stå åpen, og start backend i en annen terminal med `pnpm --filter backend dev`. -`db-tunnel.sh` scriptet er lagt inn som et script i `/package.json`, og kan kjøres med `pnpm db:tunnel`. +#### Windows +Start tunnelen i PowerShell: +```powershell +ssh -N -L 5433:localhost:5432 brukernavn@it2810-02.idi.ntnu.no +``` +Alternativt kan scriptet kjøres direkte i Git Bash eller WSL med ./scripts/db-tunnel.sh. Portsjekken i scriptet bruker lsof, som ikke finnes i Git Bash, men den hoppes da bare over. -###### test-select.sh +#### Verifiser -Det andre scriptet er `test-select.sh`, dette er et enkelt script som kjører en spørring mot en database på `localhost:5432`. Hvis tunnellen fungerer skal dette returnere dette: +Med tunnelen åpen, fra rot i repoet: +```bash +pnpm --filter backend exec tsx --env-file=.env -e " +import pg from 'pg'; +const c = new pg.Client(process.env.DATABASE_URL); +await c.connect(); +console.log((await c.query('SELECT count(*) FROM games')).rows); +await c.end(); +" ``` - count --------- - 120067 -(1 row) -``` -For å kunne kjøre dette scriptet trenger man postgres-client. Dette kan lastes ned med `sudo apt update && sudo apt install postgresql-client` på debian/ubuntu, og med `brew install libpq` på mac. +Skal skrive ut `[ { count: '120067' } ]`. + +#### Mulige feil +1. Connection refused på 5433 betyr at tunnelen ikke kjører. +2. Connection timed out mot VM-en betyr som regel at VPN mangler. +3. Password authentication failed betyr feil passord eller rolle i DATABASE_URL. diff --git a/db/ssh-tunnel.md b/db/ssh-tunnel.md deleted file mode 100644 index c0f0de44..00000000 --- a/db/ssh-tunnel.md +++ /dev/null @@ -1,53 +0,0 @@ -## Felles -#### Konfigurere `.env` -1. Koble til NTNU VPN hvis du er utenfor campus. -2. Kopier `backend/.env.example` til `backend/.env` -3. Fyll inn verdien til `VM_USER`, og `PASSORD` i `DATABASE_URL`. - -`backend/.env` skal da se ut slik: -``` -VM_USER= -VM_HOST=it2810-02.idi.ntnu.no -DATABASE_URL=postgresql://webapp:@localhost:5433/gamesdb -PORT=3001 -TUNNEL_PORT=5433 -``` - -#### Start tunnelen -Gå til rot i repo (dvs. `T02-Project-2` mappen) og kjør kommandoen: -```bash -pnpm db:tunnel -``` - -La terminalen stå åpen, og start backend i en annen terminal med `pnpm --filter backend dev`. - -## Windows - -OpenSSH følger med Windows 10 og 11. Bash-scriptet fungerer ikke via pnpm db:tunnel, fordi pnpm kjører scripts gjennom cmd. - -#### Start tunnelen i PowerShell: -```powershell -ssh -N -L 5433:localhost:5432 brukernavn@it2810-02.idi.ntnu.no -``` -Alternativt kan scriptet kjøres direkte i Git Bash eller WSL med ./scripts/db-tunnel.sh. Portsjekken i scriptet bruker lsof, som ikke finnes i Git Bash, men den hoppes da bare over. - -## Verifiser - -Med tunnelen åpen, fra rot i repoet: - -```bash -pnpm --filter backend exec tsx --env-file=.env -e " -import pg from 'pg'; -const c = new pg.Client(process.env.DATABASE_URL); -await c.connect(); -console.log((await c.query('SELECT count(*Kopier backend/.env.example til backend/.env og fyll inn VM_USER, VM_HOST, TUNNEL_PORT og DATABASE_URL (med webapp-rollen og port 5433).) FROM games')).rows); -await c.end(); -" -``` - -Skal skrive ut `[ { count: '120067' } ]`. - -#### Mulige feil -1. Connection refused på 5433 betyr at tunnelen ikke kjører. -2. Connection timed out mot VM-en betyr som regel at VPN mangler. -3. Password authentication failed betyr feil passord eller rolle i DATABASE_URL.