Totuus API-versiointistrategioista

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!

‍