AI Commercen storefrontit tukevat kauppiaskohtaista, kustomoitavaa REST-rajapintaa, jonka partnerit voivat kehittää kauppiaan tarpeiden ympärille. Sama palveluton (serverless) storefront-funktio, joka palvelee verkkokaupan käyttöliittymää, tarjoaa myös /rest/*-polun alla toimivan REST-rajapinnan. Tämä artikkeli on syväluotaava opas: kerromme mallin arkkitehtuurista, miksi se on hyödyllinen, kuinka partneri lisää oman palvelunsa ja mitä kaikkea sen avulla voi toteuttaa.

1. Taustaa: Composable Commerce ja miksi se on tärkeää

Composable Commerce -ajattelumallissa jokainen osa-alue (kuten tuotehallinta, asiakashallinta, tilausten käsittely, hakutoiminto, jne.) voidaan toteuttaa erillisinä palikoina eli micro serviceinä. Nämä micro servicet kommunikoivat keskenään API-rajapintojen kautta. Perinteisen monoliittisen arkkitehtuurin sijaan Composable Commerce -malli tarjoaa:

• Joustavuutta: Uusia ominaisuuksia voi luoda nopeammin, kun jokaista osaa voidaan kehittää ja testata toisistaan riippumatta.
• Laajennettavuutta: Voit lisätä kolmansien osapuolien palveluita (esim. uusia maksuratkaisuja, haku- tai ERP-integraatioita) helpommin, ilman massiivisia muutoksia ydinjärjestelmään.
• Nopeampaa tuotekehitystä: Kumppanit voivat kehittää ja julkaista omia laajennuksiaan itsenäisesti, ja AI Commerce hallinnoi turvallisuuden ja infrastruktuurin.

2. Ratkaisun ydin: kustomoitava /rest/*-rajapinta storefrontissa

Jokaisella kauppiaalla on oma storefront-funktionsa (AWS Lambda), joka renderöi verkkokaupan. Sama funktio tarjoaa /rest/*-polun alla REST-rajapinnan, jonka partneri räätälöi. Partnerin ei tarvitse pystyttää erillistä palvelua, omaa AWS-tiliä tai omia julkaisuavaimia — laajennus elää samassa storefront-projektissa.

2.1 Mitä tämä tarkoittaa kumppaneille?

Yksi funktio, kaksi tehtävää

• Sama storefront-Lambda palvelee sekä verkkokaupan käyttöliittymän että /rest/*-rajapinnan. Erillistä mikropalvelua tai omaa API Gatewayta ei tarvita.

Partneri lisää vain palvelutiedostoja

• Partneri kirjoittaa oman logiikkansa yksittäisinä JavaScript-tiedostoina storefront-projektin src/rest/services/-kansioon. Tiedoston polku vastaa URL-polkua, joten src/rest/services/orders.js vastaa reittiä /rest/orders.

Ydinkehys on AI Commercen ylläpitämä

• Reititin ja GraphQL-yhteys ovat AI Commercen ylläpitämiä, ja ne päivittyvät main-haarasta automaattisesti kaikille kaupoille. Partneri ei kosketa ydintiedostoihin, joten kehyksen päivitykset eivät aiheuta yhteensopivuus- tai merge-konflikteja partnerin oman koodin kanssa.

Yhteys AI Commerceen GraphQL-rajapinnan kautta

• Palvelut kutsuvat AI Commercen GraphQL-rajapintaa palvelinpuolella. Tunnistautuminen hoidetaan palvelimella osana kehystä — erillistä istuntoa tai uutta kirjautumista ei tarvita eikä tueta. Näin kauppadata (tuotteet, tilaukset, asiakkaat) on käytettävissä virallisen ja vakaan rajapinnan kautta ilman suoraa tietokantayhteyttä.

Yhteinen domain ja CloudFront

• Kauppiaan domainin takana on CloudFront, joka ohjaa /rest/*-pyynnöt suoraan storefront-funktiolle. Reitti ei ole välimuistitettu, joten myös kirjoittavat kutsut (POST, PUT, DELETE) toimivat oikein.

3. Käyttökohteet: milloin partneri tarvitsee omaa REST-rajapintaa?

• ERP-integraatiot: Partneri voi synkronoida tilaukset tai tuotetiedot kauppiaan ERP-järjestelmään omalla /rest/*-palvelullaan, joka lukee ja kirjoittaa dataa AI Commercen GraphQL-rajapinnan kautta.
• Haku- ja suodatinpalvelut: Jos AI Commercen natiivi haku ei riitä, partneri voi tuoda oman logiikkansa tai ulkoisen palvelun ja tarjota sen kauppiaalle /rest/*-reitin kautta.
• Uudet ominaisuudet: Partneri voi laajentaa tilaus-, asiakas- tai tuotekäsittelyä kauppiaskohtaisilla reiteillä (esim. webhookit, validoinnit, lisälogiikka) säilyttäen täyden yhteensopivuuden ydintietorakenteiden kanssa.

4. Tekninen toteutus: REST-palvelu käytännössä

Partneri lisää palvelunsa storefront-projektin src/rest/-rakenteeseen. Ydinkehys — reititin ja GraphQL-asiakas — on valmiina, joten partneri lisää vain palvelutiedostot.

4.1 Kansiorakenne

src/
 └─ rest/
     ├─ router.js          # Ydinreititin (AI Commercen ylläpitämä)
     ├─ safeGraphqlClient.js  # Julkinen GraphQL-asiakas (AI Commercen ylläpitämä)
     └─ services/          # Partnerin omat palvelut
         ├─ example.js     # GET /rest/example
         └─ orders.js      # /rest/orders

4.2 Palvelutiedosto

Jokainen palvelutiedosto vie ulos yhden tai useamman HTTP-metodin käsittelijän. Tiedoston sijainti määrää URL-polun, joten uusi reitti syntyy pelkästään lisäämällä tiedosto services/-kansioon.

// src/rest/services/example.js
import { executePublicGraphQL } from "../safeGraphqlClient.js"

export const GET = async () => {
  const data = await executePublicGraphQL(
    `query { products(limit: 1, offset: 0) { id name price } }`,
    {}
  )
  return { statusCode: 200, body: data.products }
}

Sama tiedosto voi viedä ulos myös POST-, PUT-, PATCH- ja DELETE-käsittelijät kirjoittaville toiminnoille.

Vain hyväksyttyä julkista dataa. Palvelutiedostot kutsuvat executePublicGraphQL-funktiota, joka sallii vain hyväksytyn julkisen osajoukon GraphQL-skeemasta — julkista tuote- ja sisältödataa, kuten tuotteet, kategoriat, brändit ja saatavuus. Kyselyt ovat vain luku -tyyppisiä: mutaatiot, subscriptionit, introspektio, kenttäaliakset ja mikä tahansa hyväksytyn osajoukon ulkopuolinen kenttä hylätään virhekoodilla REST_GRAPHQL_OPERATION_NOT_ALLOWED ennen kuin pyyntö saavuttaa GraphQL:n. Tämän asiakkaan kautta ei ole saatavilla asiakas-, tilaus-, maksu-, ylläpitäjä-, salaisuus- tai muuta yksityistä dataa. AI Commerce ylläpitää hyväksyttyä osajoukkoa ja laajentaa sitä harkitusti. Suorat ERP- ja taustajärjestelmäintegraatiot, jotka tarvitsevat koko GraphQL-rajapinnan, käyttävät edelleen omia tenant-tunnisteitaan.

4.3 Tunnistautuminen ja rajoitukset

• GraphQL-tunnistautuminen hoidetaan palvelinpuolella osana kehystä. Partnerin ei tarvitse käsitellä tunnisteita palvelukoodissa.
• GraphQL-tunnukset ovat valmiiksi konfiguroituina storefrontin palvelinpuolen ympäristömuuttujina (asetettu serverless.yml:ssä, AI Commercen ylläpitämä). Kehyksen GraphQL-asiakas käyttää niitä automaattisesti; jos kutsut GraphQL-rajapintaa suoraan, luet ne palvelimella process.env:stä. Muuttujilla ei ole VITE_-etuliitettä, joten ne eivät päädy selaimeen. Arvoja ei tarvitse pyytää erikseen — ne ovat jo storefrontin ympäristössä:
  • AICC_GRAPHQL_ENDPOINT – GraphQL-rajapinnan osoite (oletus https://api.aicommerce.fi/graphql)
  • AICC_TENANT_ID – kauppiaan tunniste
  • AICC_TENANT_SECRET – kauppiaskohtainen salaisuus
  • AICC_GRAPHQL_SECRET – GraphQL-salaisuus
• Rajapinta ei käytä istuntoa eikä erillistä kirjautumista.
• Kutsumäärää rajoitetaan kauppiaskohtaisesti ylikuormituksen estämiseksi; rajan ylittyessä rajapinta palauttaa HTTP 429 -vastauksen.

5. Käyttöönotto

• Lisää palvelutiedosto kauppiaan storefront-haaran src/rest/services/-kansioon.
• Storefront rakennetaan ja julkaistaan uudelleen, jolloin uusi reitti tulee käyttöön. Erillistä palvelua tai omia julkaisuavaimia ei tarvita.
• Testaa reitti, esimerkiksi:

curl https://kauppiaan-domain.example/rest/example

• Jos kaikki on kunnossa, saat HTTP 200 -vastauksen tai muun konfiguroidun paluukoodin.

6. Miksi tämä malli on hyödyllinen?

Partnerit saavat vapauden kehittää

• Partneri lisää uusia toiminnallisuuksia lisäämällä palvelutiedostoja, ilman että AI Commercen ydintiimin täytyy tehdä integraatiota joka kerta.

Ei merge-konflikteja

• Ydinkehys elää main-haarassa ja päivittyy automaattisesti. Koska partneri koskettaa vain omia palvelutiedostojaan, kehyspäivitykset eivät törmää partnerin koodiin.

Tietoturva ja hallinta pysyvät AI Commerce -tiimillä

• Yhteys kauppadataan kulkee virallisen GraphQL-rajapinnan kautta, ei suoraan tietokantaan. AI Commerce säilyttää täyden hallinnan infrastruktuuriin.
• Tunnistautuminen hoidetaan palvelinpuolella, joten tunnisteet eivät päädy selaimeen.

Yhtenäinen käyttökokemus

• Koska /rest/* palvellaan saman domainin ja saman funktion kautta kuin verkkokauppa, partnerin palvelut näyttäytyvät yhtenäisenä osana kauppaa.

Skaalautuvuus ja kustannustehokkuus

• Storefront-funktio skaalaa automaattisesti AWS:n serverless-mallin mukaan, ja maksat vain käytöstä.

7. Yhteenveto

AI Commercen storefrontit tarjoavat kauppiaskohtaisen, kustomoitavan /rest/*-rajapinnan, jonka partneri kehittää kauppiaan tarpeiden ympärille. Malli tukee Composable Commerce -arkkitehtuuria, jossa jokainen osa-alue on erillinen mutta silti turvallisesti kytketty AI Commercen ydinpalveluihin:

• Yksi storefront-funktio palvelee sekä verkkokaupan että /rest/*-rajapinnan — ei erillistä palvelua ylläpidettäväksi.
• Palvelutiedostot src/rest/services/-kansiossa antavat partnerille vapauden ja omatoimisuuden.
• AI Commercen ylläpitämä ydinkehys pitää päivitykset konfliktivapaina.
• Virallinen GraphQL-rajapinta takaa vakaan ja turvallisen yhteyden kauppadataan.

Kiitos, että tutustuit tähän artikkeliin. Toivomme, että se antaa selkeän käsityksen siitä, miten AI Commercea voi laajentaa ja räätälöidä kauppiaskohtaisella REST-rajapinnalla. Mikäli tarvitsette lisäohjeita, voitte ottaa yhteyttä suoraan AI Commercen tukitiimiin. Onnea matkaan Composable Commerce -polullanne!