backend api docs

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.
+
+

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 `<root>/scripts`.
+`backend/.env` skal se ut slik:
+```
+# tunnel script env vars
+VM_USER=<ntnu-brukernavn>
+VM_HOST=it2810-02.idi.ntnu.no
+TUNNEL_PORT=5433
+
+# backend server env vars
+DATABASE_URL=postgresql://webapp:<PASSORD>@localhost:5433/gamesdb
+PORT=3001
+JWT_TOKEN=<server-rand-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 `<root>/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.