Skip to main content

Rajapinnan versiointi

Julkinen rajapinta käyttää päivättyjä versioita, samaa mallia kuin Shopify, joten versio, jota vasten kehität, ei muutu jalkojesi alla. Päivätyt versiot ovat karkea raja rikkoville muutoksille; version sisällä skeema kehittyy edelleen vain lisäämällä.

Versioiden nimet​

Version nimi on YYYY-MM, jossa kuukausi on vuosineljänneksen alku: 2026-01, 2026-04, 2026-07, 2026-10. Uusi päivätty versio julkaistaan vain silloin, kun tulee rikkova muutos — neljännekset ilman rikkovia muutoksia ohitetaan, joten versioita on melko harvassa.

Lisäksi on unstable-versio, joka seuraa kehityksen kärkeä ja jonka avulla muutoksia voi tarkastella ennen vakaata julkaisua. Älä rakenna sen varaan tuotantointegraatioita.

Version valinta​

Kaksi tapaa, tärkeysjärjestyksessä:

  1. URL-polku (suositus): sijoita versio päätepisteeseen — …/backend/<subdomain>/api/2026-07/graphql. Se on yksiselitteinen, välimuistiystävällinen ja helppo kopioida.
  2. Pyynnön otsake: lähetä X-Api-Version: 2026-07 pelkkään päätepisteeseen …/backend/<subdomain>/graphql.

Jos jätät version pois — tai nimeät tuntemattoman tai jo tuen ulkopuolelle jääneen version — pyynnön käsittelee vanhin yhä tuettu versio, ei koskaan uusin. Sinua ei koskaan siirretä hiljaisesti rikkovaan muutokseen. Kiinnitä versio nimenomaisesti jokaisessa integraatiossa, jota aiot ylläpitää.

Jokainen vastaus kertoo sen käsitelleen version X-Api-Version-otsakkeessa, joten tiedät aina, mikä sopimus vastasi — ja huomaat poikkeaman, jos olit luottanut oletuskäyttäytymiseen.

Tukijakso​

Jokaista vakaata versiota tuetaan vähintään 12 kuukautta, ja se on vähintään 9 kuukautta päällekkäin seuraavan kanssa. Käytännössä kaksi tai kolme versiota on kerrallaan käytössä, mikä antaa väljän ikkunan siirtymiselle. Version tuen päättymispäivä julkaistaan sinä päivänä, kun versio ilmestyy.

Mikä lasketaan rikkovaksi muutokseksi​

Yhden version sisällä voimme tehdä lisääviä muutoksia, ja asiakkaasi on siedettävä ne:

  • uuden tyypin, kyselyn tai mutaation lisääminen;
  • valinnaisen argumentin lisääminen olemassa olevaan kenttään;
  • kentän lisääminen objektityyppiin;
  • arvon lisääminen enum-luetteloon (älä siis koskaan oleta, että enum on suljettu).

Uusi päivätty versio on varattu aidosti rikkoville muutoksille: kentän tai tyypin poistamiselle tai uudelleennimeämiselle, nullability-vaatimusten kiristämiselle taikka argumentin tai oletusarvon merkityksen muuttamiselle. Näitä ei koskaan tapahdu olemassa olevan version sisällä — kiinnittämäsi versio säilyttää käyttäytymisensä tuen päättymiseen asti.

Poistuvat osat​

Poistuvista osista ilmoitetaan kahdella tavalla, jotta saat tiedon ennen kuin mikään hajoaa:

  • Skeemassa. Poistuva kenttä merkitään @deprecated-merkinnällä ja perustelulla, joka nimeää korvaajan. Introspektio ja GraphQL Playground näyttävät tämän automaattisesti jokaiselle asiakkaalle.
  • Vastauksessa. Kun pyyntö tosiasiassa käsittelee vanhentunutta kenttää, vastaus sisältää otsakkeen X-Api-Deprecated-Reason (ja vastaavan extensions.deprecations-merkinnän), joka nimeää juuri ne poistuvat osat, joihin pyyntö osui — poistuva osa näkyy siis lokeissasi heti, kun törmäät siihen, ilman että sinun tarvitsee etsiä sitä.

Vanhentunut kenttä säilytetään julkaistun vähimmäisajan, ennen kuin se poistetaan jossakin myöhemmässä päivätyssä versiossa.