REST, GraphQL, gRPC og WebSocket: sådan vælger du

REST

REST (Representational State Transfer) er en arkitekturstil, der bygger direkte på HTTP. Data organiseres som ressourcer med hver sin adresse, og HTTP-metoderne bestemmer, hvad der sker med dem:

GET    /wp-json/wc/v3/products        hent produkter
GET    /wp-json/wc/v3/products/42     hent ét produkt
POST   /wp-json/wc/v3/orders          opret en ordre
PUT    /wp-json/wc/v3/products/42     opdatér et produkt
DELETE /wp-json/wc/v3/products/42     slet et produkt

Eksemplet er WooCommerce’ eget REST API, som er indbygget. REST er tilstandsløst: hver forespørgsel indeholder alt, serveren skal bruge, inklusiv godkendelse, og svarene er typisk JSON, der kan caches med almindelige HTTP-headers. Det er enkelt, understøttet overalt og let at teste med værktøjer, alle udviklere kender, og det er grunden til, at så mange offentlige API’er er bygget sådan.

Resten af HTTP bruges også. Statuskoden fortæller, hvordan det gik: 200 er et svar, 201 betyder, at noget blev oprettet, 401 og 403 handler om adgang, 404 om noget, der ikke findes, og 429 om, at klienten spørger for tit. Lister kommer i sider, så en klient henter fx 100 produkter ad gangen og følger næste side, i stedet for at få hele kataloget i ét svar. Og versionen står i adressen (v3), så API’et kan ændre sig, uden at eksisterende integrationer går i stykker.

Godkendelse sker med en nøgle, der følger med hver forespørgsel. WooCommerce bruger et nøglepar, som du opretter under WooCommerce → Indstillinger → Avanceret → REST API, og WordPress selv har applikationsadgangskoder under din brugerprofil. Begge dele skal sendes over HTTPS, og hver integration bør have sine egne nøgler, så du kan lukke én uden at røre de andre.

Svagheden er, at API’et bestemmer, hvilke felter du får. Skal en app vise et produkt med anmeldelser og lagerstatus, kan det kræve tre kald, der hver returnerer langt mere, end der er brug for. Det er præcis det problem, GraphQL blev lavet for at løse.

GraphQL

GraphQL blev udviklet af Facebook og vender modellen om: der er ét endpoint, og klienten beskriver selv præcis de data, den vil have.

query {
  product(id: 42) {
    name
    price
    reviews(first: 3) { rating author }
  }
}

Svaret har præcis den form, forespørgslen beskrev, og data fra flere sammenhængende objekter hentes i ét kald. API’et er beskrevet i et skema med typer, så værktøjer kan validere forespørgsler og generere dokumentation. Det gør GraphQL stærkt til apps og separate frontends med mange forskellige skærmbilleder.

Læsning kaldes queries, og ændringer kaldes mutations: at lægge en vare i kurven eller oprette en ordre er en mutation, der også selv vælger, hvilke felter den vil have tilbage. WordPress har ikke GraphQL indbygget, men udvidelsen WPGraphQL tilføjer det, og der findes en tilsvarende udvidelse til WooCommerce. Det er den typiske vej, når en webshop får en separat frontend bygget i fx React.

Prisen er en mere kompleks server. Fordi forespørgslerne typisk går til samme adresse med POST, virker almindelig HTTP-caching ikke af sig selv, så man bruger i stedet faste, gemte forespørgsler eller cache på serversiden. Og fordi klienten bestemmer, hvor dybt den spørger, skal serveren sætte grænser for, hvor tunge forespørgsler må være, så én klient ikke kan lægge den ned.

gRPC

gRPC er Googles svar på kommunikation mellem tjenester, hvor hastighed og strenge kontrakter betyder mest. Klienten kalder funktioner på serveren, og beskederne er defineret i det kompakte binære format Protocol Buffers. Kontrakten skrives i en .proto-fil:

service Lager {
  rpc HentBeholdning (VareRequest) returns (Beholdning);
}

message VareRequest { string sku = 1; }
message Beholdning  { string sku = 1; int32 antal = 2; }

Ud fra filen genereres klient- og serverkode i mange sprog, så begge sider altid er enige om, hvad en besked indeholder. Det kører over HTTP/2 med streaming i begge retninger, og det er derfor udbredt inde i større systemer, hvor mange små tjenester kalder hinanden tusindvis af gange i sekundet.

Til gengæld kan en browser ikke kalde gRPC direkte. Det kræver varianten gRPC-Web og en proxy, der oversætter imellem. Binære beskeder er også sværere at fejlsøge end JSON, så gRPC er sjældent det rigtige valg til en offentlig integration eller til en webshop, der skal tale med eksterne systemer.

WebSocket

De tre andre starter altid med, at klienten spørger. WebSocket er anderledes: efter et indledende HTTP-håndtryk bliver forbindelsen stående åben, og både server og klient kan sende beskeder, når de vil. Håndtrykket er en almindelig HTTP-forespørgsel, der beder om at skifte protokol:

GET /live HTTP/1.1
Host: eksempel.dk
Upgrade: websocket
Connection: Upgrade

Svarer serveren ja, er det ikke længere HTTP, men en tovejsforbindelse, der kører over samme TCP-forbindelse, krypteret som wss:// på samme måde som HTTPS. Det giver meget lav forsinkelse og er særligt velegnet til chat, live-notifikationer og dashboards, der opdateres løbende.

Til gengæld bruger hver åben forbindelse ressourcer på serveren, forbindelser skal genoprettes, når de ryger, og almindelig PHP-hosting er ikke bygget til det, fordi PHP afslutter hver forespørgsel, så snart svaret er sendt. Skal en WordPress-side have realtid, kører WebSocket-delen derfor typisk som en separat tjeneste ved siden af eller hos en udbyder, der er bygget til det. Skal serveren kun sende opdateringer til browseren og ikke omvendt, er Server-Sent Events ofte et lettere alternativ.

Webhooks: når systemet selv siger til

Webhooks er ikke en API-stil på linje med de fire, men de hører med, fordi de løser det problem, de fleste webshops faktisk har: at få besked, når noget sker. I stedet for at dit lagersystem spørger WooCommerce hvert minut, om der er kommet nye ordrer, sender WooCommerce selv en HTTP-forespørgsel til lagersystemet, i det øjeblik ordren oprettes.

I WooCommerce opretter du dem under WooCommerce → Indstillinger → Avanceret → Webhooks og vælger, hvilken hændelse der skal udløse dem, fx en ny ordre eller et opdateret produkt, og hvilken adresse der skal modtage dem. Hver besked signeres med en hemmelig nøgle i headeren X-WC-Webhook-Signature, så modtageren kan kontrollere, at den faktisk kommer fra din shop. Modtageren skal svare hurtigt, og den bør kunne tåle, at samme besked kommer mere end én gang. Fejler leveringen, tæller WooCommerce det, og efter fem fejl i træk slår den webhooken fra, så nogen skal holde øje med den. Mange integrationer kombinerer de to: webhooks til at få besked, og REST til at hente eller rette de data, beskeden handler om.

Sammenligning

Forskellene kort, side om side:

Sådan vælger du

Fire spørgsmål afgør det i de fleste tilfælde:

1. Skal andre end dig selv bruge API’et? Så REST. Det kan alle kalde, og det er det, udviklere forventer.
2. Har klienterne meget forskellige behov for data? En app, en webshop-frontend og et kassesystem, der hver vil have sit udsnit, taler for GraphQL.
3. Er det kun dine egne tjenester, der taler sammen, og tæller hvert millisekund? Så er gRPC værd at se på.
4. Skal data frem i det øjeblik, de ændrer sig, og ofte? WebSocket til begge veje, Server-Sent Events eller webhooks, hvis det kun går én vej.

Svarer du nej til de tre sidste, er REST næsten altid det rigtige. Det er det enkleste at bygge, drive og fejlsøge, og det er det, de systemer, en webshop skal tale med, understøtter.

Hvad betyder det for en webshop?

Integrationer til en WooCommerce-shop bygges typisk med REST, fordi WooCommerce, betalingsløsninger, fragtfirmaer og de fleste ERP- og regnskabssystemer tilbyder REST API’er. Kombinér det med webhooks, hvor et system selv sender en besked til et andet, når noget sker, fx når en ordre oprettes eller en lagerstatus ændres. Så slipper du for at spørge igen og igen.

GraphQL giver mening, hvis du bygger en separat frontend eller app oven på WordPress, hvor der findes udvidelser, der tilføjer et GraphQL API. gRPC og WebSocket er sjældne i almindelige webshops, men kan være relevante i større løsninger med egne tjenester eller live-funktioner.

Uanset stil gælder det samme: brug HTTPS, giv hver integration sine egne nøgler med kun de rettigheder, den har brug for, håndtér fejl og gentagelser, så en ordre aldrig oprettes to gange, og log, hvad der sker, så fejl kan findes.

Ofte stillede spørgsmål

Er GraphQL bedre end REST?

Nej, det er anderledes. GraphQL er stærkt, når mange forskellige klienter har brug for forskellige data. REST er enklere, lettere at cache og bedre understøttet af de systemer, en webshop typisk skal tale med.

Har WordPress et API?

Ja. WordPress har et indbygget REST API under /wp-json/, og WooCommerce tilføjer sit eget til produkter, ordrer og kunder. Begge kræver godkendelse for alt, der ikke er offentligt.

Kan WooCommerce bruge GraphQL?

Ikke som standard. Med WPGraphQL og en tilhørende WooCommerce-udvidelse kan produkter, kurv og ordrer hentes og ændres med GraphQL. Det er mest relevant, hvis shoppen får en separat frontend.

Hvornår skal jeg bruge WebSocket?

Når data skal frem med det samme og ofte, fx i en chat eller et live-dashboard. Til ting, der kun opdateres en gang imellem, er almindelige forespørgsler eller webhooks enklere.

Skal systemerne tale sammen?

Vi bygger integrationer mellem WooCommerce og lager, ERP, regnskab og fragt, og vælger den løsning, der passer til opgaven. Se mere om specialudvikling.