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!

‍

Liiketoiminnan tahti ja muutos

Versiostrategiasi perustuu moniin organisaatiosi ja asiakkaidesi tekemiin valintoihin. Nämä vaihtelevat siitä, mihin asiakassegmentteihin ja toimialoihin palvella mitä tuotteita ja palveluita tarjotaan.

organisaatiosi ja API-kuluttajien välinen suhde on merkittävä tekijä. Se vaikuttaa

• kuinka usein vaihdat sovellusliittymääsi,
• kuinka usein sinua pakotetaan, tai
• Pystytkö tekemään muutoksia tai keskeyttämään muutoksia?

Se, miten API-kuluttajat suhtautuvat ehdotettuun versioaikatauluun, riippuu virtarakenteesta:

• jos sovellusliittymäsi kuluttajat ovat riippuvaisia sinusta, voit sanella, milloin he vaihtavat versioita;
• jotkut API-kuluttajat ovat tehokkaampia ja vaikutusvaltaisempia, tai
• Suhde on hyvin säännelty.

‍

Jos voit tehdä muutoksia sovellusliittymään ja haluat ottaa muutokset käyttöön uusina versioina, sinun on ratkaistava ongelma versionmuutoksen ilmoittamisesta.

‍

Työkaluominaisuudet määräävät versionumeroiden käytön

API-versiointi eroaa koodin versioinnista. API-versionumerosi lisääminen ei ole ok joka kerta, kun sovellusliittymän toteuttava koodi tai dokumentaatio muuttuu. Vain kun varsinainen käyttöliittymä tai joissakin tapauksissa käyttäytyminen muuttuu, teet API-muutoksen. Hämmentän ihmisiä aina sanomalla, että sovellusliittymät tarvitsevat 2 x DevOps. Tarkoitan sitä, että sovellusliittymälläsi, sen käyttöliittymällä, mahdollisesti OpenAPI-määritelmällä kuvatulla, on yksi elinkaari, ja sovellusliittymää toteuttavalla koodilla on elinkaari.

Jossain määrin ne eivät ole riippuvaisia toisistaan. Voit tehdä kirjoitusvirheen korjauksen OpenAPI-määritelmään muuttamatta koodia tai koodin laskentalogiikkaa muuttamatta esimerkiksi käyttöliittymää.

Koodisi tulisi käyttää semanttista versiointia, eli sinun tulee päivittää versionumeroa jatkuvasti suurilla, pienillä ja korjaustiedostoilla 1.1.1. Keskustelu API-versioinnista alkaa yleensä uusissa ryhmissä tai sovellusliittymissä seuraavasti: ”Pitäisikö meidän laittaa versionumero URI-polulle, kyselyparametreille, mukautetuille otsikoille vai käyttää sisällöneuvottelua.” Mutta sinulla ei ole vapaata valintaa siitä. Ja sinun ei ehdottomasti pitäisi tehdä sitä, koska se on ”hyvä koodauskäytäntö”.

Jokaisen käyttöliittymän versionumeron muutoksen yhteydessä, sinun API-kuluttajien 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ä API-kuluttajien tekniikka ja työkalut ja vielä enemmän API-hallintaalustasi pystyvät käsittelemään. Varsinkin vanhat työkalut ovat nirsoja ja voivat käsitellä vain polussa olevia versionumeroita. Jotkin API-hallinta-alustat on rakennettu tukemaan API-tuotteita tai -suunnitelmia, joissa API-version muutokset voidaan piilottaa tuote- ja tilauskerroksen taakse.

Jos käytät versionumeroita osoittaaksesi muutoksia sovellusliittymäsi, harkitse sen lisäämistä vain, jos otat käyttöön rikkovan muutoksen. Ja vain, jos tämä muutos rikkoo kaikki asiakkaat heidän näkökulmastaan. Joskus se voi olla hämmentävää, myönnän. On joitain poikkeustapauksia, joissa sovellusliittymän kuluttajat kokevat muutoksen, vaikka sovellusliittymän suunnittelu ei muutu.

Yhdellä asiakkaallamme oli palveluhäiriö, koska API-palveluntarjoaja muutti yhtäkkiä sovellusliittymän todennusmenetelmää. Näin sähköpostin, jonka API-palveluntarjoajien tuki oli lähettänyt asiakkaamme valituksen jälkeen. Vastauksessa todettiin, että ”tämä ei ollut API-muutos; muutimme vain todennusta.” Voisimme väittää tuon lausunnon semantiikkaa, mutta tärkeintä on, että sovellusliittymän kuluttaja, asiakkaamme, koki palveluhäiriön. Joten muutos oli murtumassa; se ei ollut taaksepäin suuntautuvaa. Tässä ei ole kiistelyä API-kuluttajan kokemuksesta.

Jos sovellusliittymäsi ominaisuutta ei käytetä, se ei voi rikkoutua.

Kerron sinulle salaisuuden. Jos sitä ei käytetä, se ei voi rikkoutua. Jos aloitat pienestä, tiedät sovellusliittymäsi kuluttajien tarpeet, tarkastelet lokeja ja tilastoja nähdäksesi, käyttääkö joku ominaisuutta, jota aiot rikkoa vai ei, ja muuten jatkat vain uusien päätepisteiden ja attribuuttien lisäämistä, voit pitää kiinni samasta pääversiosta ja vain siitä tulevina vuosina. Tarvitset muutoksen vain, kun teet laajan uudelleensuunnittelun, joka vaikuttaa moniin tai kaikkiin päätepisteisiin tai teet merkittäviä liiketoimintalogiikkamuutoksia.

Oletetaan, että olet juuri paljastanut muutaman päätepisteen, joilla on minimaaliset määritteet. Olet varma, että kaikkea tarvitaan, suunnitellaan täydellisesti ja vahvistetaan tulevien API-kuluttajien kanssa. Miksi et lisäisi asioita samaan API-versioon ja harkitsisi dokumentaation versiointia tai julkaisutietojen päivittämistä? Tällä tavalla niiden, jotka ovat jo kytkettyneet sovellusliittymään, ei tarvitse muuttaa koodiaan ja voivat vain aloittaa uusien ominaisuuksien käytön.

Poikkeustapauksia on, kuten aina. Yksi alustan tarjoaja paljasti uudet henkilötietoryhmät olemassa olevasta päätelaitteesta. Tämä loi tietosuojaloukkauksen ja oli murtava muutos, vaikka käyttöliittymä ei muuttunut. Joten kun on kyse uusien ominaisuuksien lisäämisestä sovellusliittymään, se on ok, mutta varo, ovatko nämä ominaisuudet vain enemmän dataa. Tämä esimerkkitapaus päättyi siihen, että kolmannen osapuolen sovelluspalveluntarjoaja suljettiin pois liiketoiminnastaan, koska heitä estettiin käyttämästä sovellusliittymää sen jälkeen, kun asiakkaat saivat tietää tietosuoja-ongelmasta. Ja sovellusliittymää käyttävä sovelluspalveluntarjoaja ei ollut tehnyt mitään väärää, paitsi ehkä heillä olisi pitänyt olla parempia testauskäytäntöjä.

Niin, onko API-tiimisi tarpeeksi kypsä tuottamaan mahdollisimman vähän elinkelpoisia versioita ja tekemään loistavaa sovellusliittymän suunnittelua ja kehittämistä? Tämä vaikuttaa tarpeeseesi tehdä murtavia muutoksia tai kykyyn välttää niitä. Arvioi tiimin valmiudet tutkia ja visioida API-kuluttajien tulevia tarpeita. Mihin API-tuotteesi tai niiden paljastamat resurssit, palvelut tai tuotteet ovat menossa?

‍

Kehittyvät API-versiostrategiat

API-versioiden strategisella tasolla tulisi kehittyä kohti API-kuluttajien eli sisäisten tiimien, asiakkaiden tai kumppaneiden arvonluontia koskevien odotusten muutoksia.

Olet ehkä aloittanut ”Company X API: lla”. Sitten huomaat, että tämä on liian suuri ja altistat liikaa liian monille kuluttajasegmenteille. Voit kehittyä yrityksenä tarjoamaan useita SaaS-, data- tai muita tuote- tai palvelumuunnelmia, joihin sovellusliittymäsi on tiiviisti kytketty. Joten jaat sovellusliittymäsi tuotteen ja version mukaan tuoteversioiden mukaan.

Sitten huomaat, että on joitain päätepisteitä, jotka

a) ovat yhteisiä monille tuotteille tai

b) rajoittuvat vain joihinkin tiettyihin API-kuluttajasegmentteihin.

c) hinnoittelun tulisi olla erilainen kuin muilla.

Joten päädyt jakamaan API-tuotteesi arvoehdotusten tai käyttötapausten mukaan.

Tämän pitäisi olla helppoa, kun otetaan huomioon asiakas-, kumppani- ja API-kuluttajaymmärryksesi sekä yleinen etenemissuunnitelmasi ja tuotevisiosi. Toivottavasti, sinulla on ne. Kysymys kuuluu, miten näet sovellusliittymäsi kehittyvän? Mitä resursseja se paljastaa, ja mikä on sen elinkaari? Sillä on merkitystä, jos sovellusliittymä on kytketty autoon pilvessä olevan koneoppimisalgoritmin sijaan. Jälkimmäistä on helpompi ja nopeampi muuttaa, jos sovellusliittymä muuttuu.

Lopulta teet asiat oikein ja tarjoat fantastisen sovellusliittymän. API-kuluttajat eivät ole huomanneet, että sovellusliittymäsi rikkoutuu usein (vaikka olisit tehnyt kaikki tarvittavat muutokset). Annat selkeän etenemissuunnitelman, joka perustuu asianmukaiseen API-kuluttajien ymmärrykseen. API-kuluttajien tulisi olla iloisia ja tietoisia. 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 inspiraatiota seuraavan kerran, kun sinun on mietittävä API-versiostrategioita!

‍