Siirry suoraan sisältöön.
Hyvät käytännöt kehittäjille
Ohjelmointirajapintojen suunnittelu julkisessa hallinnossa
  1. Oppaan aloitussivu
  2. Ennen hankintaa
  3. Kehittämisen aikana
  4. Ohjelman tai sovelluksen valmistuttua
    1. Julkaise tietomalli ja lähdekoodi avoimesti
    2. Tue ohjelmistokehittäjiä
    3. Luo laadukas käyttöönottoprosessi
    4. Julkaise elinkaari ja luo versiointi
      1. Tee versiointi suunnitelmallisesti
      2. Erilaiset tyylit versioida
      3. Muista viestiä versioinnista ja elinkaaresta
    5. Tue kokeiluja ja hyödyntämistä
    6. Poista käytöstä suunnitellusti
  5. Sanasto

Julkaise elinkaari ja luo versiointi

Tee versiointi suunnitelmallisesti

Ohjelmointirajapintojen versiointi on tapa hallita ja päivittää toiminnallisuuksia. Versioinnin avulla voit tehdä muutoksia ohjelmointirajapintaan ilman, että ne rikkovat ohjelmointirajapintaa käyttäviä sovelluksia.

Versioinnin avulla eri käyttäjät voivat hyödyntää eri versioita ilman, että heidän tarvitsee jatkuvasti päivittää koodiaan uusien muutosten myötä.

Versioinnin avulla voidaan

  • tarjota uusia ominaisuuksia
  • pitää huolta yhteensopivuudesta taaksepäin
  • antaa kehittäjille aikaa siirtyä vanhoista versioista uudempiin.

Kun teet tietomallin huolellisesti, vähennät versioinnin tarvetta.

Päivitetty: 5.5.2026

Erilaiset tyylit versioida

Eri versiointityyleissä on sekä etuja että haittoja.

Usein RESTful-arkkitehtuurityylin kanssa tarvitaan versiointia. GraphQL-ohjelmointirajapinnoissa versiointitarvetta on vähemmän ja niissä hyödynnetään usein alla olevan taulukon ensimmäistä tapaa.

RESTful-arkkitehtuurin ohjelmointirajapinnan versiointityylejä

Tapa

Käytännön esimerkit

Kuvaus

URL-osoitteen kautta

https://esimerkki.fi/fi/v1/

https://esimerkki.fi/fi/v2/

Hyvää: Välimuistin käyttö on helppoa.
Huonoa: Versiopäivitys voi vaatia suuria muutoksia asiakasohjelmistoihin.

Kyselyn parametrin avulla

api/…/tuotteet?versio=1

api/…/tuotteet?versio=2

Hyvää: Suoraviivainen toteutus.

Huonoa: Vaikeampi hyödyntää, jos parametrejä on paljon.

HTTP ylätunnisteen (header) avulla

curl -H “Accepts-version: 1.0”
http://www.example.com
/api/products

curl -H “Accepts-version: 2.0”
http://www.example.com
/api/products

Hyvää: Ei kasvata URL-osoitteen pituutta.

Huonoa: Käyttää räätälöityjä ylätunnisteita.

Versiointi resurssin formaattimuodon pyynnön yhteydessä

curl -H “Accept: application/vnd.xm.device+json;
version=1”

curl -H “Accept: application/vnd.xm.device+json;
version=2”

Hyvää: URL-osoite ei muutu.

Huonoa: Vaikeampi testata ja kokeilla verkkoselaimen avulla.

Taulukko esittää erilaisia mekanismeja version ilmaisuun. Sen lisäksi on hyödyllistä pohtia, millaisia sisällöllisiä muutoksia versioidaan ja miten versioidaan. Tähän kysymykseen voi saada apua esimerkiksi semanttisesta versioinnista (Semantic Versioning 2.0.0 | Semantic VersioningAvautuu uuteen ikkunaan.).

Päivitetty: 5.5.2026

Muista viestiä versioinnista ja elinkaaresta

Toimiva API-versiointi rakentuu elinkaariajattelusta, oikeista teknologiaratkaisuista ja riittävästä viestinnästä.

On tärkeää tiedottaa

  • uuden version julkaisusta
  • versioon tehdyistä muutoksista
  • siitä, kuinka kauan vanhaa versiota tuetaan.

Päivitetty: 5.5.2026

Oletko tyytyväinen tämän sivun sisältöön?

Sanasto