Etusivu
Palvelut
keyboard_arrow_down
Integroitu tieto- ja tietoarkkitehtuuripalveluFutudemy oppimis- ja innovaatio-ohjelmaAPI-First APIOps -työpajatAPI -universumin kaupallistaminenAPI terveystarkastusAPI-dokumentaation kehittäminen
AsiakastarinoitaYritysBlogi
Ota yhteyttä!
API-talous

Totuus API-versiointistrategioista

Totuus API-versiointistrategioista

Totuus API-versiointistrategioista on, että kyse ei ole vapaasta valinnasta. Asiakkaasi, kumppanisi sekä sinun ja heidän tuotteesi ja elinkaaresi vaikuttavat valintaasi.

Totuus API-versiointistrategioista

Marjukka Niinioja

Perustajakumppani

Olet varmasti kuullut API-versiointistrategioista, jos tarjoat ohjelmointirajapintoja. Kehitystiimisi on saattanut käydä monia keskusteluja parhaasta vaihtoehdosta, mutta minulla on uutisia. Se mihin sijoitat API-versionumerosi ei ole strateginen päätös. 

Liiketoiminnan vauhti ja muutos

Versiointistrategiasi on seurausta monista organisaatiosi ja asiakkaidesi tekemistä valinnoista. Nämä vaihtelevat sen mukaan, mitkä asiakassegmentit ja toimialat palvelevat mitä tuotteita ja palveluita tarjota.  

 organisaatiosi ja API-hyödyntäjiesi välinen suhde ovat merkittävä tekijä. Siihen vaikuttaa 

  • kuinka usein muutat APIa,
  • kuinka usein on pakko, tai 
  • Pystytkö tekemään muutoksia tai tekemään rikkovia, taaksepäin yhteensopimattomia muutoksia? 

Miten API-hyödyntäjäsi ottavat vastaan ehdottamasi versiointiaikataulun riippuu valtasuhteista:

  • jos API-hyödyntäjäsi ovat riippuvaisia sinusta, voit sanella, milloin he vaihtavat versioita; 
  • jotkin API-hyödyntäjät ovat voimakkaampia ja vaikutusvaltaisempia, tai 
  • suhde on erittäin säännelty.

‍

Jos voit tehdä muutoksia APIin ja haluat ottaa muutokset käyttöön uusina versioina, sinun on ratkaistava, miten version muutos ilmoitetaan.

‍

Työkalun ominaisuudet sanelevat versionumeroiden käytön

API-versiointi eroaa koodin versioinnista. Ei ole ok kasvattaa APIn versionumeroa aina, kun koodi, joka toteuttaa APIn tai dokumentaatio muuttuu. Vain silloin, kun rajapinta tai joissakin tapauksissa  APIn käyttäytyminen todella muuttuu, teet todellisen muutoksen APIin. Hämmennän aina ihmisiä sanomalla, että rajapinnat tarvitsevat 2 x DevOpsia. Tarkoitan, että APIlla, eli sen rajapinnalla, joka on mahdollisesti kuvattu OpenAPI-määritelmällä, on yksi elinkaari, ja koodilla, joka toteuttaa APIn toiminnallisuuden on  erillinen elinkaarensa.

Ne eivät jossain määrin ole riippuvaisia toisistaan. Voit tehdä kirjoitusvirheen OpenAPI-määritykseen muuttamatta koodia tai esimerkiksi muuttaa koodin laskentalogiikkaa muuttamatta rajapintakuvausta.

Koodisi tulisi käyttää semanttista versiointia, eli sinun pitäisi jatkuvasti päivittää versionumeroa suurilla, pienillä ja korjaustiedostoilla (1.1.1.). Keskustelu API-versioinnista etenee usein seuraavasti uusissa tiimeissä tai kun on kyse uudesta APIsta: "Pitäisikö meidän laittaa versionumero URI-polkuun, kyselyparametreihin, header-osioon vai sisältöön." Oikeasti tämä ei ole vapaasti valittava asia. Ja sinun ei todellakaan pitäisi valita vaihtoehtoa vain, koska se kuuluu "hyvään koodaustapaan". 

Jokaisen rajapinnan versionumeron muutoksen yhteydessä API-hyödyntäjien on muutettava koodiaan. Ja he eivät pidä siitä. Se maksaa heille, ja heidän järjestelmänsä saattavat rikkoutua, vaikka muutos ei aiheuttaisi heille ongelmia.

Muista tarkistaa, mitä teknologiaa ja työkaluja APIn hyödyntäjät, ja mikä tärkeintä API-hallintaratkaisusi, pystyy käsittelemään. Erityisesti vanhat työkalut ovat nirsoja ja pystyvät käsittelemään vain polun versionumeroita. Jotkin API-hallintaratkaisut on rakennettu tukemaan API-tuotteita tai palvelutasopaketteja, joissa API-versio voidaan piilottaa tuotteen ja tilauskerroksen taakse. 

Jos käytät versionumeroita ilmaisemaan muutoksia APIssa, harkitse sen lisäämistä vain, jos otat käyttöön rikkovan muutoksen. Ja vain jos tämä muutos rikkoo asiakkaita heidän näkökulmastaan. Se voi joskus olla hämmentävää, myönnän. On joitakin poikkeustapauksia, joissa API-hyödyntävät kokevat muutoksen, vaikka rajapinta ei muutu.

Eräällä asiakkaallamme oli palveluhäiriö, koska APIn palveluntarjoaja muutti yhtäkkiä APIn tunnistautumistapaa. Näin sähköpostin, jonka API-palveluntarjoajan asiakaspalvelu oli lähettänyt sen jälkeen, kun asiakkaamme oli valittanut. Vastauksessa todettiin, että "tämä ei ollut API muutos; muutimme vain käyttäjätunnistusta."  Voisimme väitellä tämän lausunnon sanamuodoista, mutta tärkeintä on, että API-hyödyntäjä, asiakkaamme, koki palveluhäiriön. Joten muutos oli rikkova; se ei ollut taaksepäin yhteensopiva. Tästä API-hyödyntäjän käyttökokemuksesta ei voi kiistellä. 

Jos jotakin APIn ominaisuutta ei käytetä, se ei voi rikkoutua.

Kerron sinulle salaisuuden. Jos sitä ei käytetä, se ei voi rikkoutua. Jos aloitat pienestä, tunne API-hyödyntäjiesi tarpeet, katso lokeja ja tilastoja nähdäksesi, käyttääkö kukaan ominaisuutta, jonka aiot rikkoa vai ei, ja muuten lisää vain uusia päätepisteitä ja attribuutteja, voit pysyä samassa pääversiossa ja vain siinä tulevina vuosina. Tarvitset muutoksen vain, kun teet laajan uudelleensuunnittelun, joka vaikuttaa moniin tai kaikkiin päätetapahtumiin, tai teet merkittäviä liiketoimintalogiikan muutoksia.

Oletetaan, että olet juuri avannut muutamia rajapinnan ominaisuuksia käyttöön minimaalisella sisällöllä. Olet varma, että kaikki on tarpeellista, suunniteltu täydelliseksi ja validoitu API-hyödyntäjien kanssa tulevaisuutta varten. Miksi et vain lisäisi ominaisuuksia olemassaolevaan API-versioon ja harkitse  ainoastaan dokumentaation versiointia tai versiotiedotteen päivitystä? Näin niiden, jotka jo hyödyntävät APIasi ei tarvitse muuttaa koodiaan, ja he voivat vain alkaa käyttää uusia ominaisuuksia.

On olemassa poikkeustapauksia, kuten aina. Yksi alustan tarjoaja paljasti uusia henkilötietoryhmiä olemassa olevasta rajapintakutsusta. Tämä aiheutti yksityisyydenloukkauksen mahdollisuuden ja oli rikkova muutos, vaikka käyttöliittymä ei muuttunut. Joten kun on kyse uusien ominaisuuksien lisäämisestä APIin, se on ok, mutta varo etteivät nämä ominaisuudet esimerkiksi tarjoa enemmän dataa. Tämä esimerkkitapaus päättyi siihen, että 3. osapuolen sovellustoimittaja joutui lopettamaan liiketoimintansa, koska heitä estettiin käyttämästä APIa kun asiakkaat saivat tietää tietosuojaongelmasta. Eikä kyseinen APIa hyödyntänyt sovellustoimittaja ollut tehnyt mitään väärää, paitsi ehkä heillä olisi pitänyt olla paremmat testauskäytännöt. 

Niinpä siis, onko sinun API tiimisi riittävän kypsä tuottamaan vähintään elinkelpoisia versioita ja pärjäämään hyvin API-suunnittelussa ja kehityksessä? Tämä vaikuttaa tarpeeseesi toteuttaa rikkovia muutoksia tai kykyysi välttää niitä. Arvioi tiimin valmiudet selvittää ja visioida API-hyödyntäjien tulevaisuuden tarpeet. Mihin ovat API-tuotteesi tai ne resurssit, palvelut tai tuotteet, joiden käytön ne mahdollistavat menossa? 

‍

Kehittyvät API-versiointistrategiat

APIsi versioinnin tulisi strategisella tasolla kehittyä kohti muutoksia API-hyödyntäjien, eli sisäisten tiimiesi, asiakkaidesi tai kumppaniesi arvonluontiodotuksissa.

Olet ehkä aloittanut "Yritys X API:lla". Sitten huomaat, että siitä tulee liian suuri ja että se paljastaa liikaa tietoa liian monille hyödyntäjäsegmenteille. Saatat kehittyä yrityksenä tarjoamaan useita SaaS-, data- tai muita tuote- tai palveluvariaatioita, joihin API on tiukasti kytketty. Joten jaat APIn tuotekohtaisesti ja versioittain tuoteversioiden mukaan.

Sitten huomaat, että on joitain toimintoja, jotka

a) ovat yhteisiä monille tuotteille tai

b) rajoittuvat vain joihinkin erityisiin API-hyödyntäjäsegmentteihin. 

c) pitäisi olla erilainen hinnoittelu kuin muilla. 

Joten päädyt pilkkomaan API-tuotteesi arvolupausten tai käyttötapausten mukaan.

Tämän pitäisi olla helppoa, kun otetaan huomioon asiakkaasi, kumppanisi ja API hyödyntäjä ymmärrys ja yleinen etenemissuunnitelmasi ja tuotevisiosi. Toivottavasti sinulla on ne. Kysymys kuuluu, miten näet APIsi kehittyvä? Mitä resursseja se avaa käyttöön ja mikä on sen elinkaari? Sillä on merkitystä, jos APIsi on yhteydessä autoon tai pilvessä olevan koneoppimisalgoritmin sijaan. Jälkimmäistä on helpompi ja nopeampi muuttaa, jos API tarvitsee muutoksen.

Loppujen lopuksi teet asiat oikein ja tarjoat fantastisen API. API-hyödyntäjäsi eivät ole huomanneet APIn rikkoutuvan usein (vaikka olisit ottanut käyttöön kaikki tarvittavat muutokset). Annat selkeän etenemissuunnitelman, joka perustuu API-hyödyntäjien ymmärtämiseen. API-hyödyntäjiesi olisi oltava iloisia ja heille olisi tiedotettava asiasta. He innovoivat kanssasi ja auttavat sinua luomaan etenemissuunnitelmasi. He ovat sitoutuneet tekemään muutoksia tai ottamaan käyttöön tarjoamasi uudet ominaisuudet. Loppujen lopuksi he tekivät yhteistyötä prosessissa.

Toivottavasti tunnet olosi inspiroituneeksi seuraavan kerran, kun sinun on ajateltava API-versiointistrategioita!

‍

Älykkäitä liiketoimintamalleja ja ekosysteemi supertietokoneille
Julkinen sektori
API-universumin kaupallistaminen

Älykkäitä liiketoimintamalleja ja ekosysteemi supertietokoneille

Read story
navigate_next
Kohti APIen avulla toimivien tuotteiden yhteiskehittämistä
Teollisuus
API-universumin kaupallistaminen

Kohti APIen avulla toimivien tuotteiden yhteiskehittämistä

Read story
navigate_next
API-kehittäjäkokemuksen skaalaus kasvutavoitteisiin.
SaaS
API terveystarkastus

API-kehittäjäkokemuksen skaalaus kasvutavoitteisiin.

Read story
navigate_next
Explore more stories
Future of Banking: A Down-Under Perspective on Fintech
September 7, 2023
Innovatiiviset API tuotteet

Future of Banking: A Down-Under Perspective on Fintech

Matkailuala murroksessa - Amadeuksen API-liiketoimintamalli
August 8, 2023
API- ja liiketoimintaekosysteemit

Matkailuala murroksessa - Amadeuksen API-liiketoimintamalli

Onko liiketoimintamallissasi tilaa API-tuotteille?
August 4, 2023
API-talous

Onko liiketoimintamallissasi tilaa API-tuotteille?

Tilaa sähköpostimme nyt ja ole osa kukoistavaa API -kulttuuria!

Blogit, videot, whitepaperit, podcastit ja tapahtumat - tutustu kattavaan resurssikirjastoomme, joka kattaa kaiken, mitä sinun tarvitsee tietää seuraavista asioista: API-hallinta, kulttuurin muutos, APIOps Cycles -menetelmiemme tehokkuus.

Kiitos! Lähetyksesi on vastaanotettu!
Hups! Jokin meni vikaa lomaketta lähetettäessä.
Osaango
Osaango Oy is a private limited company  registered in Finland.
Trade register: 2881365-2
VAT registration: FI2881365
2DUNS: 368558872
‍Trusted partner
Company
Etusivu
Yritys
Ota yhteyttä
Blogi
Asiakastarinoita
Osaango Academy
Palvelut
Koe APIOpsin teho API-First ajattelun kera
Integrated Information & Data Architecture Service
Kaupallista API-universumi
API terveystarkastus
API Documentation Enhancements
Futudemy - Innovation and Learning Program
Contact
send
info@osaango.com
perm_phone_msg
+358 9 25166110
Tekijänoikeus © 2023 Osaango. Kaikki oikeudet pidätetään.


