FedExin API:en versiointi

FedExin API:en versiointi

FedEx käyttää semanttista versiointia API-versioiden hallintaan. Jokaiselle versiolle on tunniste, joka on muotoa pääversio.aliversio (esim Ship API 1.1). Uusi pääversio tarkoittaa, että muutos ei ole taaksepäin yhteensopiva, ja uusi aliversio sisältää taaksepäin yhteensopivia muutoksia.

FedEx noudattaa yksinkertaista URI-versiointia. Tämä ilmenee siten, että URI-polussa esiintyy vain pääversion numero. Huomaa, että URI-polkuun ei sisälly aliversion numeroa. Tässä menetelmässä käytetään URI-reititystä osoittamaan API-liittymien tarkat versiot.

Esimerkki: /ship/v1/shipments

Versiointikäytäntöä ohjaavat periaatteet

Tavoitteenamme on julkaista FedExin API-liittymille pääversioita vain harvoin, ja tuemme edellistä pääversiota kahden vuoden ajan uuden version julkaisun jälkeen. Esimerkiksi, jos pääversio N julkaistaan, versio N-1 saa tukea kahden vuoden ajan version N julkaisun jälkeen.

Esimerkki: Pääversio V1.0 julkaistaan vuonna 2020. Jos pääversio V2.0 julkaistaan vuonna 2021, versio V1.0 lakkautetaan vuonna 2023.

Aliversiot tukevat useimpia uusia toimintoja ja ominaisuuksien päivityksiä.

Esimerkki: Pääversion 1.0 jälkeen julkaistavat aliversiot 1.1, 1.2 jne. sisältävät uusia toimintoja ja ominaisuuksien päivityksiä.

Kaikilla ajan hetkillä tietyn API:n kaikilla päätepisteillä on sama pääversion numero. Dokumentaation uusin versio on saatavilla vain FedEx Developer Portalissa. Jokaisen API:n yleiskuvaussivulla on kuitenkin muutosloki, joka kuvaa pää- ja aliversioiden muutokset.

Milloin API:sta julkaistaan pääversio?

Pyrimme minimoimaan API-liittymiemme pääversioiden määrän. On kuitenkin tilanteita, joissa uusi pääversio on julkaistava. Seuraavassa on joitakin merkittävimpiä syitä pääversion julkaisemiselle:

• Käytössä oleva luetteloarvo poistetaan tai arvo tai sen muoto muuttuu pyynnössä tai vastauksessa.
  

  Esimerkki: locationSearchCriterion-elementin luetteloarvo “GEOGRAPHIC_COORDINATES” poistetaan versiossa N, ja päivämäärä muuttuu YY-MM-DD-muodosta MM-DD-YYYY-muotoon ja sijaintityyppi vaihtuu vastauksessa FEDEX_ONSITE-arvosta ONSITE-arvoksi.

• Käytössä oleva luetteloarvo poistetaan pyynnössä tai vastauksessa.
  

  Esimerkki: pickupType-elementti poistetaan N-version hintapyynnöstä (tai nimetään uudelleen).

• Käytössä oleva menetelmä poistetaan.
  

  Esimerkki: FedEx Express -merkintöjen luomisessa ja peruuttamisessa käytettyä menetelmää ei enää tueta versiossa N.

• Käytössä oleva elementti, joka on ollut valinnainen tai ehdollinen, muuttuu pakolliseksi pyynnössä.
  

  Esimerkki: kirjausnumero on nyt pakollinen elementti FedEx Express® Freight -lähetyksissä N-versiossa.

• API:n rakenne muuttuu.
  

  Esimerkki: pyynnön ja vastauksen rakenne järjestetään uudelleen.

• Virhekoodit ja virheilmoitukset muuttuvat.
  

  Esimerkki: virhekoodi muuttuu INCORRECT.WEIGHT -> WEIGHT.LIMIT.EXCEEDED.

Milloin API:sta julkaistaan aliversio?

• Lisätään uusi luetteloarvo.
  

  Esimerkki: serviceType-elementtiin lisätään uusi kuljetusmahdollisuus N-versiossa.

• Lisätään uusi elementti.
  

  Esimerkki: lisätään uusi valinnainen elementti, joka sisältää tulliselvittäjän puhelinnumeron ulkomaanlähetyksissä.

• Lisätään uusi menetelmä.
  

  Esimerkki: N-versioon lisätään uusi menetelmä, jolla muokataan ulkomaankauppa-asiakirjoja sen jälkeen, kun ne on lähetetty palvelimeen.

• Käytössä olevasta pakollisesta elementistä tehdään vapaavalintainen.
  

  Esimerkki: asiakirjan tunnus on nyt valinnainen, koska FedEx voi hakea asiakirjan tunnuksen käyttäjätietojen perusteella.