Versiot ja yhteensopivuus

API:lla on yksi pääversio, /v1, ja se vain kasvaa. Tänään kirjoitettu integraatio toimii edelleen, kun uusia ominaisuuksia tulee: mitään, mihin se nojaa, ei nimetä uudelleen, poisteta eikä anneta uutta merkitystä.

Versionumero

API:lla on versionumero, kuten 1.62.0. Se muuttuu jokaisessa julkaisussa:

• alaversion numero, kun jotain lisätään: päätepiste, kenttä, tapahtuma;
• korjausversion numero, kun kuvausta tai viestin tekstiä korjataan eikä mikään muu muutu.

Voit milloin tahansa tarkistaa, mitä versiota osoite palvelee:

Myös GET /v1/health -vastauksessa on version, mutta se on osoitetta palvelevan Sursa-julkaisun versio eikä API:n versio.

Alaversiota ei valita: jokaisen pyynnön palvelee nykyinen alaversio. Alla olevien sääntöjen ansiosta se on turvallista.

Mikä voi muuttua /v1-versiossa

Nämä muutokset voivat tulla missä tahansa alaversiossa. Kirjoita integraatiosi niin, etteivät ne riko sitä:

• Uudet päätepisteet.
• Uudet valinnaiset parametrit ja pyyntöjen kentät. Pyynnöt ilman niitä toimivat kuten ennenkin.
• Uudet kentät vastauksissa, objekteissa ja tapahtumissa.
• Vastausten luetteloarvojen uudet arvot, kuten uusi kortin tila tai uusi tapahtumatyyppi.
• Uudet virhekoodit ja uudet vastausotsakkeet.
• Väljemmiksi muuttuvat rajat: pidempi enimmäispituus, laajempi arvoalue.
• Virheiden message-tekstien ja kuvausten uudet sanamuodot.

Mitä koodisi täytyy sietää

• Ohita kentät, joita et tunne. Älä epäonnistu, kun vastauksessa on enemmän kenttiä kuin odotat, äläkä käytä tiukkoja skeemoja, jotka hylkäävät ne.
• Hyväksy enum-arvot, joita et tunne. Mikä tahansa vastauksen luetteloarvokenttä voi laajentua. Käsittele tuntematonta arvoa arvona ”muu” äläkä virheenä.
• Ohita tapahtumatyypit, joita et tunne, sekä webhookeissa että virroissa.
• Käsittele tuntemattomat virhekoodit niiden HTTP-tilan mukaan: ks. Virheet.
• Älä ole riippuvainen kenttien järjestyksestä JSON-objekteissa etkä viestien tarkasta tekstistä.

Mikä ei koskaan muutu /v1-versiossa

• Polkua, parametria, kenttää tai enum-arvoa ei koskaan nimetä uudelleen eikä poisteta.
• Kentän tyyppi ei koskaan muutu, eikä kenttä koskaan saa uutta merkitystä, kuten uusia yksiköitä.
• Tänään hyväksyttyä pyyntöä ei myöhemmin hylätä.
• Onnistuneen vastauksen tilakoodi pysyy samana.
• Virhekoodit säilyttävät merkityksensä, ja virhevastausten detail-kenttä säilyttää muotonsa.
• Tapahtumatyyppejä ei koskaan nimetä uudelleen eikä poisteta, ja niiden data saa vain uusia kenttiä.

Yhteensopivuuden rikkovat muutokset

Jos yhteensopimaton muutos joskus tarvitaan, se julkaistaan uutena pääversiona, kuten /v2, /v1-version rinnalle. /v1 toimii edelleen muuttumattomana, ja molemmat versiot toimivat rinnakkain.

Kun reitti aiotaan poistaa käytöstä:

1. Se merkitään määrittelyssä merkinnällä deprecated ja kirjataan muutoslokiin sen päivämäärän kanssa, jolloin se poistetaan käytöstä.
2. Sen vastauksissa ovat otsakkeet Deprecation: true ja Sunset: <date>.
3. Se toimii vähintään 180 päivää ilmoituksen jälkeen. Organisaatioille, joiden API-avaimet käyttävät sitä, ilmoitetaan kirjallisesti vähintään 90 päivää etukäteen.
4. Käytöstä poistumisen päivän jälkeen se vastaa vielä 90 päivän ajan 410-tilalla ja koodilla api.gone.

Seuraa Deprecation-otsaketta lokeissasi tai valvonnassasi: se on varhaisin merkki siitä, että käyttämäsi reitti on poistumassa.

Ajan tasalla pysyminen

Tämän portaalin muutosloki luettelee jokaisen julkaisun ja kertoo, mitä siinä lisättiin ja mitä merkittiin vanhentuneeksi. Ennen kuin päivität oman integraatiosi, vertaa sen koodia merkintöihin siitä versiosta alkaen, jota vasten rakensit sen.