{"canonical_url":"https://engineer.company/nb/glossary/graphql/","content_markdown":"# GraphQL\n\n## Hva det er\n\nGraphQL er et spørrespråk for API-er sammen med kjøretidsmiljøet som utfører\nspørringene på serveren. Klienten sender et dokument som navngir nøyaktig de\nfeltene den vil ha, og serveren svarer med data i samme form. Spesifikasjonen\nbeskriver det som et språk og en utførelsesmotor for klient-server-programmer.\nDen opplyser at GraphQL ble laget i 2012, at arbeidet med det som åpen standard\nbegynte i 2015, og at det siden 2019 har vært en leveranse fra GraphQL\nSpecification Project under Joint Development Foundation. Den nyeste utgaven er\nfra september 2025.\n\nAlt utgår fra skjemaet en tjeneste publiserer: et sett typer, hver med navngitte\nfelt, og hvert felt med sin egen type. De innebygde skalartypene er `Int`,\n`Float`, `String`, `Boolean` og `ID`, og en tjeneste kan legge til egne\nskalarer, for eksempel én for UUID-er. Enhver type kan være null med mindre den\ner merket med `!`, så en `String!` kan aldri være null, og lister skrives i\nhakeparenteser: `[LineItem!]!` er en liste som alltid er til stede og aldri\ninneholder null. Man kan også stille spørsmål til selve skjemaet. Gjennom\nintrospeksjonsfeltene `__schema` og `__type` kan en klient spørre en tjeneste\nhva den tilbyr, og utviklerverktøy og klientbiblioteker bygger nettopp på det.\n\nDet finnes tre slags operasjoner. En `query` er med spesifikasjonens ord «a\nread-only fetch», altså en henting som bare leser; en `mutation` er en skriving\nfulgt av en henting; og en `subscription` er en langvarig forespørsel som\nleverer data som svar på en rekke hendelser over tid. På serveren står det en\nfunksjon bak hvert felt, som regel kalt en resolver, og den leverer verdien til\nfeltet. Tjenesten validerer først en operasjon mot skjemaet og kaller først\nderetter resolverne for feltene operasjonen har valgt. Feltene på toppnivå i en\n`mutation` kjøres ett om gangen i stedet for parallelt, så to skrivinger i samme\nforespørsel ikke kan gå i beina på hverandre.\n\nSpesifikasjonen foreskriver verken transport eller serialiseringsformat. HTTP er\ndet vanligste valget, og der ligger et GraphQL-API på én enkelt URL, som regel\nmed endelsen `/graphql`, og svarer i JSON, det vanligste formatet. Klienten\nsender en POST der JSON-kroppen inneholder `query`-teksten og ved behov\n`variables`. En server kan også ta imot GET for `query`-operasjoner, men en\n`mutation` må alltid sendes som POST. Svaret har resultatet under `data` og alt\nsom gikk galt, under `errors`. GraphQL Foundations veiledning om alt dette\nfølger en GraphQL-over-HTTP-spesifikasjon som fortsatt er et utkast.\n\n## Hvorfor det er viktig\n\nI de fleste HTTP-API-er er det serveren som bestemmer hva hvert endepunkt\nreturnerer. En skjerm som trenger statusen til en ordre og navnet på kunden, får\nenten hele ordren og hele kunden, altså mer enn den ba om, eller må sende én\nforespørsel per ressurs og sette svarene sammen selv. Spesifikasjonen kaller de\nto problemene over-fetching og under-fetching. GraphQL snur det hele på hodet:\nklienten spør på nivå med enkeltfelt og får nøyaktig de feltene tilbake, verken\nmer eller mindre. Én forespørsel kan også følge relasjoner, fra en ordre til\nordrelinjene og videre til kunden, fordi forespørselen har samme form som\ndataene den får tilbake.\n\nTypesystemet lønner seg to ganger. Hver operasjon valideres mot skjemaet før\nnoen resolver kjører, så et felt med skrivefeil eller et argument av feil type\navvises som helhet før noe i det hele tatt er utført, og verktøy kan fange de\nsamme feilene mens koden fortsatt skrives. Og siden en klient bare får feltene\nden har valgt, koster et nytt felt ingenting for eksisterende klienter. Det gjør\ndet praktisk å videreutvikle et API uten versjonsnumre: et nytt felt kommer til\nved siden av det gamle, det gamle merkes med `@deprecated` og en begrunnelse,\ndet forblir gyldig så eksisterende klienter ikke går i stykker, og det fjernes\nnår ingen klient bruker det lenger.\n\nKostnadene er reelle, og de fleste kommer av at man går utenfor maskineriet HTTP\nselv har. Entiteter identifiseres ikke lenger av URL-er, og alt går til én\nadresse, som regel med POST, mens det er GET-forespørsler som vanligvis regnes\nsom cachebare som standard. Den cachingen et REST-API får gratis fra\nmellomleddene, må bygges opp igjen med vilje. Statuskoden forteller ikke lenger\nhele historien, for et svar med både data og feil er fortsatt en suksess på\nHTTP-nivå. Klienten setter nå sammen forespørsler serveren aldri har sett, så én\nenkelt forespørsel kan be om mye arbeid, og å beskytte serveren mot det er\ntjenestens jobb, ikke noe GraphQL gjør for den. Resolvere per felt er lette å\nskrive, men skrevet naivt blir de svært pratsomme mot databasen bak dem.\n\n## Slik ser det ut i praksis\n\nEn liten del av et skjema for ordrer, hver med ordrelinjer og en kunde:\n\n```graphql\ntype Query {\n  order(id: ID!): Order\n}\n\ntype Order {\n  id: ID!\n  status: String!\n  items: [LineItem!]!\n  customer: Customer\n}\n\ntype LineItem {\n  name: String!\n  quantity: Int!\n}\n\ntype Customer {\n  name: String!\n}\n```\n\nEn skjerm som viser statusen, ordrelinjene og navnet på kunden, sender denne\noperasjonen til `/graphql` i kroppen på en POST, med `{\"id\": \"7421\"}` som\nvariabler:\n\n```graphql\nquery OrderSummary($id: ID!) {\n  order(id: $id) {\n    status\n    items {\n      name\n      quantity\n    }\n    customer {\n      name\n    }\n  }\n}\n```\n\nAnta at ordren og linjene blir hentet, men at tjenesten bak `customer` er nede.\nSvaret inneholder likevel alt som kunne leveres. Feltet som feilet, kommer\ntilbake som null, og en oppføring i `errors` forteller hva som gikk galt, hvor i\ndokumentet det skjedde (linje 8, kolonne 5 er `customer`), og hvilken sti i\nsvaret det gjelder:\n\n```json\n{\n  \"data\": {\n    \"order\": {\n      \"status\": \"open\",\n      \"items\": [{ \"name\": \"notebook\", \"quantity\": 2 }],\n      \"customer\": null\n    }\n  },\n  \"errors\": [\n    {\n      \"message\": \"Customer service unavailable\",\n      \"locations\": [{ \"line\": 8, \"column\": 5 }],\n      \"path\": [\"order\", \"customer\"]\n    }\n  ]\n}\n```\n\nFordi `customer` er deklarert slik at det kan være null, stopper skaden ved det\nfeltet. Hadde det vært `Customer!`, ville feilen ha forplantet seg opp til\nforelderen, og hele ordren ville ha kommet tilbake som null. Og fordi `data`\nikke er null, svarer serveren med en 2xx-status selv om det finnes en feil: HTTP\nhar ingen statuskode for delvis suksess. En klient som bare ser på statuskoden,\nvil behandle svaret som komplett.\n\nDet motsatte designet, der serveren eier formen på hvert svar, er det et\nprosjekt i porteføljen på dette nettstedet bygget: en\n[JSON-passthrough-arkitektur fra Postgres til API-et](/nb/portfolio/designed-a-json-passthrough-from-postgres-to-api/).\nDer setter PostgreSQL-funksjoner sammen hele svaret som JSON, og Go-handleren\nvideresender det urørt, så når man endrer hva en funksjon returnerer, endres\nogså det klienten mottar, uten at noen redigerer en eneste linje handlerkode.\nFrontenden avhenger der direkte av formen databasen gir den. I GraphQL er det\nklienten som navngir feltene, og serveren må være klar til å levere enhver\nkombinasjon av dem som skjemaet tillater.\n\n## Hvor det går galt\n\n**Ett felt, tusen databasekall.** Resolvere er små funksjoner, én per felt, og\nen naiv tjeneste kaller dem ett objekt om gangen. En liste over ordrer med\nkunden til hver ordre koster da ett databasekall for listen og ett til for hver\nordre i den. GraphQL Foundations veiledning kaller dette N+1-problemet og viser\ntil batching: oppslagene som blir bedt om innenfor et kort tidsrom, samles og\nsendes til databasen som én forespørsel, med et verktøy som Facebooks\nDataLoader.\n\n**Én forespørsel ber om alt.** Fordi det er klienten som skriver operasjonen,\nkan ett dokument nøste venners venner mange nivåer ned, gjenta et dyrt felt\nunder hundre aliaser eller pakke mange operasjoner inn i én forespørsel. Hver av\ndem er gyldig GraphQL, og hver av dem kan legge beslag på serveren. Forsvaret\nligger hos tjenesten: paginer listefelt, avvis operasjoner som overskrider en\nmaksimal dybde eller bredde, før utførelsen starter, sett tak på aliaser og\nbatchstørrelse, og gi for finere kontroll feltene vekter og avvis enhver\noperasjon der den anslåtte kostnaden går over budsjettet, en teknikk kjent som\nquery complexity analysis, som spesifikasjonen selv ikke gir noen regler for. Et\nAPI som bare betjener sine egne klienter, kan gå lenger med trusted documents,\nslik at bare operasjoner som er lagret på forhånd og slås opp etter hash, får\nkjøre i det hele tatt.\n\n**200 OK skjuler feilen.** Et svar med feil kan likevel være en 2xx, som i\neksempelet ovenfor. Med den eldre medietypen `application/json` går veiledningen\nlenger: en 2xx anbefales selv når en gyldig forespørsel ikke kan utføres, og\nnoen eldre servere returnerer 2xx også ved valideringsfeil. En klient, og\novervåkingen rundt den, må lese `errors` og ikke bare statuskoden. Den nyere\nmedietypen `application/graphql-response+json` gir statuskoden mening igjen,\nsiden en gyldig forespørsel som ikke lar seg utføre, da får en 4xx eller 5xx, og\nklienter bør be om den i `Accept`-headeren sin.\n\n**Cachingen slutter å virke.** Hver operasjon er en POST til den samme URL-en,\nså cachene mellom klient og server, et CDN medregnet, ser én adresse og en\nmetode de som standard ikke cacher. Det hjelper å sende `query`-operasjoner som\nGET, men et langt dokument kan overskride URL-lengden som nettlesere og CDN-er\ngodtar. Persisted queries løser begge problemene: klienten sender en hash, og\nserveren slår opp hele dokumentet før det valideres og utføres. Overalt der svar\ncaches over HTTP, må sensitive svar caches privat eller ikke i det hele tatt.\n\n**Et felt forsvinner.** Klientene velger felt ett for ett, så hvis et felt\nfjernes eller får nytt navn, går enhver klient som fortsatt velger det, i\nstykker, og ikke stille og rolig: en operasjon som nevner et ukjent felt, feiler\nvalideringen som helhet og gir ingen data i det hele tatt. Spesifikasjonen\nholder felt merket for utfasing gyldige nettopp for at eksisterende klienter ikke skal gå i\nstykker. Legg til erstatningen først, merk det gamle feltet med `@deprecated` og\nen begrunnelse som viser til det nye, og fjern det gamle feltet først når\ningenting lenger velger det.\n\n## Les mer\n\n- [GraphQL Specification Versions](https://spec.graphql.org/) — alle utgavene av\n  spesifikasjonen, fra juli 2015 til utgaven fra september 2025, pluss\n  arbeidsutkastet: språket, typesystemet, validering, utførelse og feil.\n- [Serving over HTTP](https://graphql.org/learn/serving-over-http/) — det ene\n  endepunktet, POST og GET, de to medietypene for svar og reglene for\n  statuskoder for hver av dem.\n- [Performance](https://graphql.org/learn/performance/) — GET for\n  `query`-operasjoner, persisted queries, N+1-problemet og batching.\n- [Security](https://graphql.org/learn/security/) — trusted documents, grenser\n  for dybde, bredde og batcher, query complexity analysis samt introspeksjon og\n  feildetaljer i produksjon.\n\n\u003chttps://engineer.company/nb/glossary/graphql/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Hvordan GraphQL lar klienten velge feltene den får tilbake, hva ett endepunkt koster i caching og statuskoder, og fem måter det går galt på.","formats":{"gemtext":"https://engineer.company/nb/glossary/graphql/index.gmi","gopher":"https://engineer.company/nb/glossary/graphql/gophermap","html":"https://engineer.company/nb/glossary/graphql/","json":"https://engineer.company/nb/glossary/graphql/index.json","markdown":"https://engineer.company/nb/glossary/graphql/index.md","pdf":"https://engineer.company/nb/glossary/graphql/index.pdf"},"kind":"page","language":"nb","title":"Hva er GraphQL?","url":"https://engineer.company/nb/glossary/graphql/","version":1}