WordPress REST API -versionhallinta

WordPress REST API -versionhallinta kokonaisuutena

WordPress REST API toi WordPressiin modernin sovellusrajapinnan, mutta samalla se toi mukanaan ongelman, jota perinteisessä teemakehityksessä ei juuri ollut: rajapintojen elinkaaren hallinnan. Kun API on käytössä mobiilisovelluksissa, headless-ratkaisuissa ja ulkoisissa integraatioissa, pienikin muutos voi rikkoa tuotantoympäristön ilman varoitusta.

REST API -versionhallinta ei ole WordPressissä vain numerointia. Se on sopimus sovellusten välillä. Kun se tehdään huolimattomasti, kehitys hidastuu ja luottamus katoaa. Kun se tehdään oikein, WordPressistä tulee vakaa alusta pitkäikäisille integraatioille.

Miksi versionhallinta on REST API:ssa kriittinen

API ei ole teema

Teeman tai lisäosan voi päivittää ja korjata nopeasti. API:n kuluttaja voi olla:

• mobiilisovellus sovelluskaupassa

• kolmannen osapuolen integraatio

• asiakkaan oma järjestelmä

• front-end, jota ei päivitetä samaan tahtiin

Kun REST API muuttuu, kuluttaja ei välttämättä muutu mukana. Tämä tekee taaksepäin yhteensopivuudesta kriittisen.

WordPress elää hitaammin kuin frontendit

WordPressin core päivittyy hallitusti ja suhteellisen hitaasti. Frontend-kehitys, erityisesti JavaScript-pohjaisissa sovelluksissa, elää paljon nopeammassa syklissä.

Ilman versionhallintaa REST API sitoo nämä kaksi eri rytmiä toisiinsa liian tiukasti.

WordPressin REST API -versionhallinnan perusmalli

URL-pohjainen versionointi

WordPress käyttää URL-pohjaista versionointia. Tämä näkyy suoraan endpointeissa:

/wp-json/wp/v2/posts

Tässä:

• wp on namespace

• v2 on versio

• posts on resurssi

Versio on osa polkua, ei otsake tai parametri. Tämä tekee versionoinnista eksplisiittistä ja helppoa hahmottaa.

Namespace ei ole pelkkä nimi

Namespace on WordPressin REST API:ssa tekninen rajapinta, ei vain nimeämiskäytäntö. Se:

• eristää endpointit toisistaan

• estää törmäykset

• mahdollistaa useiden versioiden rinnakkaiselon

Hyvin suunniteltu namespace on versionhallinnan perusta.

Core-API ja versionhallinnan filosofia

Miksi core käyttää v2:ta pitkään

WordPressin core-REST API on käyttänyt v2-versiota vuosia. Tämä ei tarkoita, että API olisi staattinen. Se tarkoittaa, että muutokset on tehty:

• taaksepäin yhteensopivasti

• laajentamalla, ei rikkomalla

• uusilla kentillä, ei vanhoja poistamalla

WordPress suosii evoluutiota vallankumouksen sijaan.

Breaking change on viimeinen keino

Core-API:ssa rikottavia muutoksia vältetään äärimmäisen pitkälle. Uusi versio (v3) syntyy vasta, kun:

• vanha rakenne ei enää kestä

• yhteensopivuutta ei voi säilyttää järkevästi

• hyödyt ylittävät migraation kustannukset

Tämä on hyvä malli myös custom-API:lle.

Custom REST API -endpointit ja versiointi

Versiointi on kehittäjän vastuulla

Kun rakennat omia endpointteja, WordPress ei pakota sinua versionhallintaan. Tämä on vaarallista.

Ilman versiota:

• jokainen muutos on potentiaalinen breaking change

• vanhoja asiakkaita ei voi tukea

• rollback on käytännössä mahdoton

Versionointi kannattaa tehdä heti, vaikka ensimmäinen versio tuntuisi lopulliselta.

Suositeltu malli

Yleinen ja toimiva malli on:

/wp-json/oma-sovellus/v1/resource

Tässä:

• oma-sovellus on projektikohtainen namespace

• v1 on API-versio

Kun rajapinta kehittyy, uusi versio julkaistaan rinnalle, ei päälle.

Mitä version numero oikeasti tarkoittaa

Versio ei ole koodin versio

REST API -version numero ei vastaa lisäosan tai teeman versiota. Se vastaa:

• vastauksen rakennetta

• kenttien merkitystä

• validointia ja sivuvaikutuksia

Jos endpoint palauttaa eri muotoista dataa kuin ennen, versio on vaihtunut, vaikka PHP-koodi olisi lähes sama.

Milloin versiota pitää nostaa

Versio pitää nostaa, kun:

• kenttä poistetaan tai sen merkitys muuttuu

• pakollinen kenttä lisätään

• validointilogiikka muuttuu

• käyttäytyminen muuttuu yllättävästi

Pelkkä uuden kentän lisääminen ei yleensä vaadi uutta versiota.

Rinnakkaiset versiot käytännössä

Useamman version ylläpito

Usean API-version rinnakkaiselo tarkoittaa:

• erillisiä rekisteröintejä

• osittain erillistä logiikkaa

• huolellista testausta

Tämä on tietoinen kustannus, joka maksetaan vakaudesta.

Yhteinen ydinkoodi

Hyvä käytäntö on:

• pitää bisneslogiikka yhteisenä

• tehdä versiointi vasta esityskerrokseen

• muuntaa data version mukaan

Näin muutokset eivät monistu hallitsemattomasti.

Deprekaatio: unohdettu mutta kriittinen vaihe

Vanha versio ei kuole heti

Kun uusi versio julkaistaan, vanhaa ei poisteta saman tien. Hyvä deprekaatiomalli sisältää:

• dokumentoidun aikataulun

• varoitukset lokeissa

• mahdolliset HTTP-otsakkeet

Ilman deprekaatiota versiointi on näennäistä.

WordPress ei pakota deprekaatioon

Core ei tarjoa automaattista deprekaatiomekanismia REST API:lle. Tämä on kehittäjän vastuulla ja usein se osa, joka jää tekemättä.

REST API -versionhallinta ja tietoturva

Vanha versio on myös hyökkäyspinta

Jokainen API-versio on potentiaalinen hyökkäysvektori. Siksi:

• vanhat versiot on dokumentoitava

• käyttämättömät versiot on poistettava hallitusti

• autentikointi ja authorisointi on pidettävä ajan tasalla kaikissa versioissa

Versionhallinta ei saa tarkoittaa ikuista tuen lupausta.

Dokumentaatio on osa versionhallintaa

Ilman dokumentaatiota versiolla ei ole merkitystä. Jokaisella versiolla täytyy olla:

• selkeä kuvaus

• kenttien merkitykset

• erot edelliseen versioon

Dokumentaatio on se, mitä API-kuluttaja oikeasti käyttää versionhallinnan ymmärtämiseen.

Yleisimmät virheet WordPress REST API -versionhallinnassa

Yleisin virhe on olla versionoimatta ollenkaan. Toinen on käyttää versiota, mutta muuttaa sitä silti rikkovasti. Kolmas on poistaa vanha versio liian aikaisin “siivouksen” nimissä.

Kaikki nämä johtavat samaan lopputulokseen: epäluotettava API.

Milloin versionhallinta on onnistunut

REST API -versionhallinta on onnistunut, kun:

• uusia ominaisuuksia voidaan julkaista ilman pelkoa

• vanhat asiakkaat toimivat ennustettavasti

• muutokset ovat hallittuja ja dokumentoituja

• API:n kehitys ei hidasta muuta kehitystä

Parhaimmillaan versionhallinta ei tunnu hidasteelta, vaan mahdollistajalta.

Lopuksi: API on lupaus

WordPress REST API ei ole vain tekninen rajapinta. Se on lupaus siitä, että data on saatavilla tietyssä muodossa tietyn ajan.

Versionhallinta on se mekanismi, jolla tuo lupaus pidetään. Ilman sitä REST API on vain hetkellinen ratkaisu. Sen kanssa WordPressistä tulee vakavasti otettava integraatioalusta, joka kestää aikaa, muutoksia ja kasvavia vaatimuksia.