AI Commerce GraphQL API kumppaneille

Tämä artikkeli kertoo, miten kumppanit ja integraatiotiimit käyttävät AI Commercen GraphQL API:a. Artikkelissa kuvataan, mistä julkinen API-dokumentaatio löytyy, miten pyynnöt lähetetään, mitä headereita tarvitaan ja miten rate limiting toimii.

Julkinen API-dokumentaatio

Julkinen GraphQL-skeeman referenssi on osoitteessa https://docs.aicommerce.cloud. Sen kautta voi selata käytettävissä olevia kyselyitä, mutaatioita, tyyppejä, esimerkkejä ja tarvittavia header-tietoja.

Dokumentaatiosivusto ja varsinainen API-yhteyspiste ovat tarkoituksella eri osoitteissa. Käytä docs.aicommerce.cloud-sivustoa skeeman tarkistamiseen, ja lähetä tuotantopyynnöt osoitteeseen https://api.aicommerce.fi/graphql.

Miten GraphQL-pyynnöt toimivat AI Commercessa

GraphQL-pyynnöt lähetetään HTTP POST -pyyntöinä, joiden runko on JSON-muotoinen. Pyynnön runko sisältää query-kentän ja tarvittaessa variables-kentän.

• Asiakas pyytää vain ne kentät, joita integraatio tarvitsee.
• API palauttaa datan samassa rakenteessa kuin GraphQL-kyselyn kenttävalinta.
• Jokaisessa pyynnössä täytyy olla tarvittavat tenant- ja GraphQL-tunnisteet headereissa.

Vaaditut request headerit

Jokaisessa GraphQL-pyynnössä täytyy olla seuraavat headerit.

Esimerkkipyyntö

Seuraava esimerkki hakee pienen sivun tuotteita.

query Products($limit: Int, $offset: Int) {
  products(limit: $limit, offset: $offset) {
    id
    name
    price
  }
}

Esimerkkipyyntö muuttujilla:

curl -X POST https://api.aicommerce.fi/graphql \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "X-Tenant-Secret: <your-tenant-secret>" \
  -H "X-GraphQL-Secret: <your-graphql-secret>" \
  --data '{
    "query": "query Products($limit: Int, $offset: Int) { products(limit: $limit, offset: $offset) { id name price } }",
    "variables": {
      "limit": 5,
      "offset": 0
    }
  }'

Esimerkkivastauksen rakenne:

{
  "data": {
    "products": [
      {
        "id": "632",
        "name": "Example product",
        "price": 89.9
      }
    ]
  }
}

Rate limiting ja virheet

Tuotannon GraphQL API:ssa on rate limiting palvelun vakauden suojaamiseksi. Nykyinen raja on 100 pyyntöä / 5 minuuttia / tenant.

• Jos raja ylittyy, API palauttaa vastauksen 429 Too Many Requests.
• Jos autentikointi epäonnistuu, tarkista tenant-tunniste, tenant-salaisuus ja GraphQL-käyttöoikeustunniste.
• Jos pyynnön runko on virheellinen, varmista, että JSON on kelvollinen ja että GraphQL-kysely vastaa julkista skeemaa.

{
  "error": "Too many requests, please try again later."
}

GraphQL verrattuna REST API:in

GraphQL sopii tilanteisiin, joissa integraatio tarvitsee tietyn kenttäjoukon tai haluaa hakea toisiinsa liittyviä tietoja yhdellä pyynnöllä.

Tietoturva ja onboarding

• Säilytä tenant- ja GraphQL-tunnisteet palvelinpuolella. Älä lisää niitä selaimessa ajettavaan koodiin tai julkisiin repositorioihin.
• Käytä julkista dokumentaatiota kyselyiden nimien, kenttien, argumenttien ja vastaustyyppien tarkistamiseen ennen toteutusta.
• API-tunnisteita ja onboardingia koskevissa kysymyksissä ota yhteyttä osoitteeseen info@petrosoft.fi.

Yhteenveto

• Julkinen GraphQL-dokumentaatio on osoitteessa https://docs.aicommerce.cloud.
• Tuotannon API-pyynnöt lähetetään osoitteeseen https://api.aicommerce.fi/graphql.
• Jokainen pyyntö tarvitsee headerit Content-Type, X-Tenant-ID, X-Tenant-Secret ja X-GraphQL-Secret.
• API:ssa on tenant-kohtainen rate limiting, joten integraatioiden täytyy käsitellä 429 Too Many Requests -vastaukset hallitusti.