Shopware har to REST-grænseflader, Store API og Admin API, men ingen officiel GraphQL API. Vi viser godkendelse og eksempler på kald for begge og forklarer, hvad GraphQL-projekter som SwagGraphQL kan. Til udviklere og webshops i Danmark.
REST (Representational State Transfer) er en arkitekturstil til netværksbaserede applikationer. REST API'er kaldes via HTTP, og de almindelige operationer kører over metoderne GET (læse), POST (oprette), PATCH eller PUT (ændre) og DELETE (slette). Shopware 6 stiller to REST-grænseflader til rådighed, og de bruges af webshops i Danmark på samme måde som alle andre steder:
Begge grænseflader udveksler data i JSON-format og melder resultatet tilbage med HTTP-statuskoder, for eksempel 200 ved succes eller 401 ved manglende adgang. De følgende afsnit viser godkendelse og eksempler på kald. Det grundlæggende om platformen finder du på vores side om Shopware-udvikling.
Store API er adgangen til Shopwares storefront. Sådan godkender du dig og sender de første kald.
Store API kræver en sw-access-key, der er knyttet til en saleskanal:
https://din-shop.dk/admin.Shopware leveres med en Swagger-brugerflade, hvor du kan teste Store API:
https://din-shop.dk/store-api/_info/swagger.html.sw-access-key, og bekræft.Derefter kan du afprøve alle endpoints direkte i browseren.
En produktliste henter du med en POST-forespørgsel til /store-api/product. Store API modtager søgekriterier som limit, filtre og sortering i body. Med cURL:
curl -X POST https://din-shop.dk/store-api/product \
-H "sw-access-key: DIN_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"limit": 10}'
Svaret er JSON med et array elements, der indeholder produkter med navne, priser og id'er:
{
"elements": [
{
"id": "0190d2e8f2b47c6f9d1a0c5e8b3f1a2b",
"name": "Eksempelprodukt",
"calculatedPrice": { "totalPrice": 19.99 },
"stock": 100
}
],
"total": 1
}
Headless-shops kører udelukkende via disse grænseflader. Valget mellem REST og GraphQL er derfor en arkitekturbeslutning: REST er modent og understøttes af Shopwares officielle værktøjer, mens GraphQL giver mere fleksibel indlæsning af data til komplekse frontends, men ikke har officiel status i Shopware (mere om det nedenfor).
Admin API er beregnet til backend-integrationer og giver adgang til Shopwares stamdata. Den bruger OAuth 2.0.
Med integrationens adgangsoplysninger anmoder du om et token via POST /api/oauth/token:
curl -X POST https://din-shop.dk/api/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "DIT_ADGANGSNOEGLE_ID",
"client_secret": "DIN_SIKKERHEDSNOEGLE"
}'
Svaret indeholder et token, der er gyldigt i ti minutter:
{
"token_type": "Bearer",
"expires_in": 600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}
Med tokenet kalder du Admin API. En produktliste henter du med GET /api/product:
curl -X GET https://din-shop.dk/api/product \
-H "Authorization: Bearer DIT_ACCESS_TOKEN" \
-H "Content-Type: application/json"
Lagerbeholdningen ændrer du med en PATCH-forespørgsel til /api/product/{produkt-id}:
curl -X PATCH https://din-shop.dk/api/product/0190d2e8f2b47c6f9d1a0c5e8b3f1a2b \
-H "Authorization: Bearer DIT_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "stock": 150 }'
Til masseændringer har Admin API sync-endpointet POST /api/_action/sync, der skriver mange poster i ét kald. Og vil du hellere have besked om ændringer end selv at spørge efter dem, kan du læse vores indlæg om webhooks i Shopware 6.
GraphQL er et forespørgselssprog, hvor klienten angiver præcis, hvilke data den har brug for. Det undgår overfetching og kan være mere effektivt end REST. I stedet for mange endpoints er der ét enkelt, som regel /graphql. Shopware tilbyder dog ingen officiel GraphQL API. GraphQL kan kun tilføjes via communityprojekter som SwagGraphQL.
SwagGraphQL er et proof of concept fra shopwareLabs, der lægger en GraphQL API oven på Shopwares kerne-API. Det bygger på biblioteket webonyx/graphql-php og integreres som plugin i Shopware 6. Projektet vedligeholdes ikke længere, blev bygget til tidlige versioner af Shopware 6 og bør ikke bruges i produktion uden omfattende tilpasninger.
Til afprøvning i et udviklingsmiljø:
# Klon repository til plugin-mappen
git clone https://github.com/shopwareLabs/SwagGraphQL.git custom/plugins/SwagGraphQL
# Installér pluginnets afhængigheder
cd custom/plugins/SwagGraphQL && composer install && cd -
# Registrér og aktivér pluginnet
bin/console plugin:refresh
bin/console plugin:install --activate SwagGraphQL
bin/console cache:clear
Efter installationen er endpointet tilgængeligt på https://din-shop.dk/graphql/query og kan kaldes med værktøjer som GraphiQL. En forespørgsel efter produkter ser sådan ud:
query {
products {
id
name
price
}
}
Har du brug for GraphQL i frontenden, bygger du i praksis dit eget lag: en BFF (Backend for Frontend) i Node.js eller PHP, der udstiller GraphQL udadtil og internt kalder Store API og Admin API. Middleware-platforme som Alumio forbinder Shopware med GraphQL-baserede systemer, men erstatter ikke en indbygget GraphQL API i Shopwares kerne. Til enkle automatiseringer mellem systemer er n8n ofte nok.
sw-access-key mangler, er forkert eller hører til en anden saleskanal./store-api/product.includes og associations), paginér resultaterne, og cache svarene.Med Store API og Admin API dækker Shopware fuldt ud integrationen af egne frontends og eksterne systemer via REST. En officiel GraphQL API findes ikke, og communityprojekter som SwagGraphQL egner sig kun til eksperimenter. Har du brug for GraphQL i frontenden, sætter du et eget lag foran REST-grænsefladerne. Korrekt konfigureret og drevet efter reglerne ovenfor er Shopwares API'er fundamentet for headless-frontends, CRM-synkronisering og automatiseringer. Vi hjælper webshops i Danmark med netop den slags integrationer. Har du brug for et plugin eller en app, støtter vi dig med udvikling af Shopware-plugins; et første overblik over din butik får du med vores shopanalyse.