Valtiovarainministeriön julkaisuja – 2022:12 Julkisen hallinnon API-periaatteet Julkisen hallinnon ICT Julkisen hallinnon API-periaatteet Valtiovarainministeriö Helsinki 2022 Valtiovarainministeriön julkaisuja 2022:12 Valtiovarainministeriö CC BY-NC-ND 4.0 ISBN pdf: 978-952-367-907-8 ISSN pdf: 1797-9714 Taitto: Valtioneuvoston hallintoyksikkö, Julkaisutuotanto Helsinki 2022 Julkaisujen jakelu Distribution av publikationer Valtioneuvoston julkaisuarkisto Valto Publikations- arkivet Valto julkaisut.valtioneuvosto.fi Julkaisumyynti Beställningar av publikationer Valtioneuvoston verkkokirjakauppa Statsrådets nätbokhandel vnjulkaisumyynti.fi https://julkaisut.valtioneuvosto.fi/ https://vnjulkaisumyynti.fi/ Kuvailulehti 28.2.2022 Julkisen hallinnon API-periaatteet Valtiovarainministeriön julkaisuja 2022:12 Teema Julkisen hallinnon ICT Julkaisija Valtiovarainministeriö Tekijä/t Miina Arajärvi, Maaret Saukonoja ja Pasi Vänttinen Kieli suomi Sivumäärä 65 Tiivistelmä Julkisen hallinnon API-periaatteet muodostavat yhteiset toimintaohjeet ja suositukset API-kehitykselle ja digitalisaation edistämiselle. API-periaatteet on kehitetty osana valtiovarainministeriön Tiedon hyödyntämisen ja avaamisen hanketta, joka toteuttaa pääministeri Marinin hallitusohjelman tietopolitikkaan, tiedon hyödyntämiseen ja avaamiseen liittyviä tavoitteita. Periaatteet on jaettu kolmelle tasolle: strateginen, taktinen ja operatiivinen. Strategisen tason periaatteet ovat kohdistettu organisaation johdolle. Strategisella tasolla kuvataan, miten ohjelmointirajapintojen kehittämiselle tulisi määrittää suunta ja tavoitteet ja miten ohjelmointirajapinnat tulisi huomioida toiminnan kehittämisessä. Taktisen tason periaatteet ovat kohdistettu organisaation tiedonhallintaa kehittäville toimijoille. Taktisen tason periaatteet ohjaavat, miten ohjelmointirajapintojen kehittämistä ja ohjelmointirajapintojen muodostamaa kokonaisuutta tulisi hallita. Operatiivisen tason periaatteet ovat kohdistettu ohjelmointirajapintoja kehittäville ja ylläpitäville toimijoille. Operatiivisen tason periaatteet ohjaavat, miten yksittäisiä ohjelmointirajapintoja tulisi kehittää ja ylläpitää. Asiasanat julkisen hallinnon ICT, API (Application Programming Interface), rajapinta, ohjelmointirajapinta, tieto, tietojärjestelmä, yhteentoimivuus, tiedonhallinta, tietopolitiikka ISBN PDF 978-952-367-907-8 ISSN PDF 1797-9714 Hankenumero VN/5386/2020 Julkaisun osoite https://urn.fi/URN:ISBN:978-952-367-907-8 https://urn.fi/URN:ISBN:978-952-367-907-8 Presentationsblad 28.2.2022 API-principer för den offentliga förvaltningen Finansministeriets publikationer 2022:12 Tema Offentliga förvaltningens ICT Utgivare Finansministeriet Författare Miina Arajärvi, Maaret Saukonoja och Pasi Vänttinen Språk finska Sidantal 65 Referat API-principerna för den offentliga förvaltningen bildar gemensamma instruktioner och rekommendationer för API-utveckling och främjandet av digitalisering. API-principerna har utvecklats som en del av finansministeriets projekt Utnyttja och öppna information genomför mål, som genomför informationspolitik och utnyttjandet och öppnandet av information i statsminister Marins regeringsprogram. Principerna är indelade i tre nivåer: strategisk, taktisk och operativ. Principerna på strategisk nivå är riktade till organisationens ledning. På den strategiska nivån beskrivs hur organisationen ska bestämma riktningen och målen för utvecklingen av applikationsprogrammeringsgränssnitten och hur applikationsprogrammeringsgränssnitten ska beaktas vid utvecklingen av verksamheten. Principerna på taktisk nivå är riktade till de aktörer som utvecklar informationshanteringen i organisationen. Principerna på taktisk nivå styr hur utvecklandet och helheten av applikationsprogrammeringsgränssnitt ska hanteras. Principerna på operativ nivå är riktade till de aktörer som utvecklar och administrerar applikationsprogrammeringsgränssnitt. Principerna på operativ nivå styr hur enskilda applikationsprogrammeringsgränssnitt ska utvecklas och administreras. Nyckelord offentliga förvaltningens ICT, API (Application Programming Interface), gränssnitt, applikationsprogrammeringsgränssnitt, information, informationssystem, interoperabilitet, informationshantering, informationspolitik ISBN PDF 978-952-367-907-8 ISSN PDF 1797-9714 Projektnummer VN/5386/2020 URN-adress https://urn.fi/URN:ISBN:978-952-367-907-8 https://urn.fi/URN:ISBN:978-952-367-907-8 Description sheet 28 February 2022 Public Administration API Principles Publications of the Ministry of Finance 2022:12 Subject Public Sector ICT Publisher Ministry of Finance Author(s) Miina Arajärvi, Maaret Saukonoja and Pasi Vänttinen Language Finnish Pages 65 Abstract The Public Administration API Principles provide common instructions and recommendations for API development and the promotion of digitalisation. The API principles have been developed under the Ministry of Finance's project on opening up and using public data, which implements the objectives related to information policy and the opening and use of public data in the Programme of Prime Minister Marin's Government. These principles have been divided into three levels: strategic, tactical and operative. Strategic principles apply to the organisation's management. These principles describe how the direction and goals of API development should be defined and how APIs should be taken into account in the development of operations. Tactical principles apply to the developers of information management in the organisation. They guide the management of API development and the organisation's system of APIs. Operative principles apply to those who develop and maintain APIs. They guide the development and maintenance of individual APIs. Keywords public sector ICT, API (Application Programming Interface), Interface, Data, Information System, Interoperability, Data Management, Information Policy ISBN PDF 978-952-367-907-8 ISSN PDF 1797-9714 Project number VN/5386/2020 URN address https://urn.fi/URN:ISBN:978-952-367-907-8 https://urn.fi/URN:ISBN:978-952-367-907-8 Sisältö 1 Johdanto. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1 Tavoitteet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2 Kohderyhmä.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3 Rajaukset.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2 Mitä API:t ovat?.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.1 Määritelmä. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.2 Arvoketju.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.3 Tyypitys.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.4 Elinkaari.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3 Periaatteet.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.1 Strateginen taso.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Periaate 1.1 Tarjoa ja hyödynnä tietoja pääsääntöisesti ohjelmointirajapintojen kautta.. . . . . . . . . . . . . . . 18 Periaate 1.2 Määritä ohjelmointirajapintojen tarjoamiselle ja hyödyntämiselle tavoitteet ja mittarit sekä hanki riittävät resurssit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Periaate 1.3 Varmista hankinnoissa yhteentoimivuus muiden tietojärjestelmien kanssa. . . . . . . . . . . . . . . 24 Periaate 1.4 Edistä sisäistä ja ulkoista yhteistyötä. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 3.2 Taktinen taso. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Periaate 2.1 Kehitä ohjelmointirajapintoja tarvelähtöisesti. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Periaate 2.2 Määritä ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen liittyvät roolit, tehtävät, vastuut ja toimintamallit.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Periaate 2.3 Kuvaa ohjelmointirajapintojen muodostama kokonaisuus.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Periaate 2.4 Tunnista ja hallitse ohjelmointirajapintoihin liittyvät riskit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 3.3 Operatiivinen taso.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Periaate 3.1 Kehitä ohjelmointirajapinnat avoimilla ja teknologiariippumattomilla standardeilla ja protokollilla.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Periaate 3.2 Kuvaa ohjelmointirajapintojen käsittelemät tiedot yhteisten ja yleisten tietomallien mukaisesti. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Periaate 3.3 Turvaa, testaa, versioi, dokumentoi ja julkaise ohjelmointirajapinnat.. . . . . . . . . . . . . . . . . . . . . 51 Periaate 3.4 Seuraa ohjelmointirajapinnoille asetettuja mittareita ja muita seurantakohteita. . . . . . . . 55 3.4 Yhteenveto periaatteista. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Lähteet.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Liitteet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Liite 1: Esimerkki ohjelmointirajapintojen riskiarvioinnista tietoriskianalyysin avulla. . . . . 64 7 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 1 Johdanto Pääministeri Marinin hallitusohjelmassa1 syvennetään tietopolitiikan johtamista ja julki- sen tiedon avoimuudesta tehdään koko tietopolitiikan kantava periaate. Lähtökohtana muun muassa on, että julkiset toimijat avaavat julkiset rajapinnat, jos ei ole erityistä syytä pitää niitä suljettuina. Valtiovarainministeriön Tiedon hyödyntämisen ja avaamisen hanke toteuttaa pääministeri Marinin hallitusohjelman tietopolitiikkaan, tiedon hyödyntämiseen ja avaamiseen liittyviä tavoitteita2. Hanke on asetettu ajalle 30.4.2020–31.12.2022. Hank- keen tavoitteena on muun muassa edistää tietojen ja toiminnallisuuksien hyödyntämistä yhteneväisellä tavalla ohjelmointirajapintojen (API) kautta. Tässä dokumentissa esitellään julkisen hallinnon ohjelmointirajapintojen (API) kehittä- mistä koskevat periaatteet ja tukimateriaali. Periaatteet muodostuvat suosituksista ja hyvistä käytänteistä julkisen hallinnon API-kehitykselle ja digitalisaation edistämiselle. Tukimateriaali ja esimerkit tarjoavat käytännönläheisiä ohjeita käyttöönoton tukemiseksi. Periaatteet tukevat tiedonhallintalaissa3 sähköiselle tietojen luovutustavalle säädettyjen vaatimusten toteuttamista. Periaatteiden viitekehyksenä on hyödynnetty Euroopan komis- sion API Frameworkia4 ja huomioitu muun muassa Euroopan yhteentoimivuusperiaat- teet koskien teknistä ja semanttista yhteentoimivuutta5. Lisäksi periaatteiden ja tukimate- riaalien valmistelussa on huomioitu sektorikohtainen sääntely, kuten INSPIRE-direktiivi6, 1 Pääministeri Sanna Marinin hallituksen ohjelma (Valtioneuvosto, 2019:31) 2 Tiedon hyödyntämisen ja avaamisen hanke (Valtiovarainministeriö, 2021a) 3 Tiedonhallintalain 22§ ja 24§ (Tiedonhallintalaki 906/2019, 2019) 4 An Application Programming Interface (API) framework for digital government. (Joint Research Centre (European Commission), 2020) 5 Euroopan yhteentoimivuusperiaatteet –täytäntöönpanostrategia. (Euroopan Komissio, 2017) 6 INSPIRE-direktiivi (Euroopan parlamentin ja neuvoston direktiivi 2007/2/EY, 2019) ja kan- sallinen täytäntöönpano (Laki paikkatietoinfrastruktuurista 421/2009, 2009) 8 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 tiedonhallintalautakunnan antamat suositukset7 sekä tiedon hyödyntämisen ja avaamisen kansalliset strategiset tavoitteet8. API-periaatteet ja tukimateriaali ottavat rajapintakehitykseen laajemmin kantaa kuin esi- merkiksi tiedonhallintalautakunnan tämänhetkiset suositukset, jotka koskevat tiedonhal- lintalain piirissä olevia teknisiä rajapintoja9. API-periaatteet kattavat paitsi tietojen myös toiminnallisuuksien tarjoamisen ja hyödyntämisen sekä organisaation sisäisillä että ulkoi- silla ohjelmointirajapinnoilla riippumatta käytetystä tiedonsiirtoprotokollasta. Viranomaiset voivat jatkokehittää periaatteita omiin tarpeisiinsa, esimerkiksi velvoittavuu- den osalta. 1.1 Tavoitteet Periaatteiden tarkoituksena on edistää julkisen hallinnon tietojen ja toiminnallisuuksien tarjoamista sekä hyödyntämistä lähtökohtaisesti ohjelmointirajapintojen avulla. Periaattei- den tavoitteena on lisätä asiakaslähtöisyyttä, yhteistyötä, semanttista ja teknistä yhteen- toimivuutta, uudelleenkäytettävyyttä, tietoturvan ja tietosuojan huomioimista sekä laatua ohjelmointirajapintojen kehityksessä. Asiakaslähtöisyys tarkoittaa sitä, että ohjelmointirajapinnan potentiaalisten hyödyntä- jien tarpeet huomioidaan ohjelmointirajapinnan koko elinkaaren ajan aina tarvekartoi- tuksesta käytöstä poistoon asti. Asiakaslähtöisesti kehitettävät rajapinnat vastaavat hyö- dyntäjien tarpeisiin ja kehittyvät jatkuvasti hyödyntäjiä paremmin palvelevaan suuntaan. Asiakaslähtöisyys kasvattaa hyödyntäjien tyytyväisyyttä ja nostaa ohjelmointirajapintojen käyttöastetta. Asiakaslähtöisyys vaatii yhteistyötä tiedon, toiminnallisuuksien ja rajapintojen tarjo- ajien sekä hyödyntäjien välillä. Yhteistyö voi olla organisaation sisäistä tai ulkoista yhteis- työtä. Sisäinen yhteistyö kattaa oman organisaation eri tasojen, tiimien ja yksiköiden väli- sen yhteistyön. Ulkoinen yhteistyö voi olla julkisen sektorin toimijoiden välistä tai julkisen ja yksityisen sektorin toimijoiden välistä yhteistyötä tai yhteistyötä kansalaisten kanssa. 7 Tiedonhallintalataukunnan suositukset (Valtiovarainministeriö, Tiedonhallintalautakunta, 2020–2021) 8 Strategiset tavoitteet ovat osa valtioneuvoston periaatepäätöstä tiedon hyödyntämiseksi ja avaamiseksi, joka on tarkoitus julkaista kevään 2022 aikana. 9 Tiedonhallintalautakunnan suositus teknisistä rajapinnoista ja katseluyhteyksistä (Valtio- varainministeriö, Tiedonhallintalautakunta, 2021:21) 9 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Yhteistyö paitsi edistää asiakaslähtöistä kehittämistä myös mahdollistaa osaamisen, koke- muksien ja ratkaisuiden jakamisen eri toimijoiden välillä. Uudelleenkäytettävyys tarkoittaa sitä, että ohjelmointirajapinnat ja niiden tarjoamat tie- dot ja toiminnallisuudet ovat löydettävissä ja hyödynnettävissä uusien ratkaisujen toteu- tuksissa. Päällekkäinen työ ja päällekkäiset ratkaisut vähenevät, kehittämistyö nopeutuu ja tuottavuus kasvaa, kun uusia ratkaisuja voidaan kehittää jo olemassa olevien tietojen, toi- minnallisuuksien ja ohjelmointirajapintojen päälle. Tekninen yhteentoimivuus tarkoittaa tiedonsiirtotekniikoiden yhteensovittamista10. Semanttinen yhteentoimivuus tarkoittaa sitä, että eri toimijoiden välillä vaihdetun tie- don merkitys säilytetään ja ymmärretään osapuolten välillä sellaisena kuin se on lähe- tetty11. Teknisesti ja semanttisesti yhteentoimivien ohjelmointirajapintojen avulla tietojen liikutettavuus paranee, kehittämistyö nopeutuu ja tuottavuus kasvaa. Tietoturvalla tarkoitetaan sitä, että käsiteltävien tietojen eheys, luottamuksellisuus ja saa- tavuus huomioidaan koko ohjelmointirajapinnan elinkaaren ajan. Tietosuojalla tarkoite- taan sitä, että ohjelmointirajapinnoissa käsiteltävät henkilötiedot on suojattu asetettujen vaatimuksien mukaisesti. Laadulla tarkoitetaan sitä, että ohjelmointirajapintojen ominaisuudet tai kyvykkyydet täyttävät hyödyntäjiensä tarpeet ja odotukset12. Laadukkaiden ohjelmointirajapintojen avulla hyödyntäjien tyytyväisyys lisääntyy ja ohjelmointirajapintojen käyttöaste kasvaa. Laatu myös nopeuttaa kehittämistyötä ja kasvattaa sitä kautta tuottavuutta. 1.2 Kohderyhmä Periaatteiden kohderyhmää ovat: y Julkisen hallinnon organisaatiot, kuten valtion virastot ja laitokset, kunnat ja kuntayhtymät, hyvinvointialueet sekä korkeakoulut ja muut oppilaitokset. y Yritykset, yhteisöt tai muut toimijat, jotka käsittelevät julkisen hallinnon tie- toja tai toteuttavat julkista hallintotehtävää. y Yritykset, yhteisöt tai muut toimijat, jotka toimittavat julkisen hallinnon orga- nisaatiolle tietojenkäsittelyyn tai tiedonhallintaan liittyviä palveluita tai ratkaisuja. 10 Teknisen yhteentoimivuuden määritelmä (Valtiovarainministeriö, 2021b) 11 Semanttisen yhteentoimivuuden määritelmä (Valtiovarainministeriö, 2021b) 12 Laadun määritys perustuu OECD:n ISO-määritelmään (OECD, 2002) 10 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 1.3 Rajaukset Periaatteet eivät koske loppukäyttäjille tarkoitettuja käyttöliittymärajapintoja. Periaatteet eivät ole kaiken kattava ohjelmointirajapintojen käsikirja tai suunnitteluo- pas. Periaatteissa ei nimetä käytettäviä teknologioita, tiedonsiirtomuotoja tai tietomalleja, mutta annetaan niistä ohjeellisia esimerkkejä. Periaatteet eivät myöskään sisällä toimialakohtaisia ohjeita tai määrityksiä, vaan niitä voi- daan toimialoittain kehittää periaatteiden päälle. 11 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 2 Mitä API:t ovat? 2.1 Määritelmä Ohjelmointirajapinnat eli API:t (Application Programming Interface) ovat dokumentoituja rajapintoja, joiden avulla ohjelmistot, sovellukset tai järjestelmät voivat vaihtaa keskenään tietoa tai toiminnallisuuksia13. Tässä dokumentissa API:lla, ohjelmointirajapinnalla ja tie- donhallintalaissa14 määritellyllä teknisellä rajapinnalla tarkoitetaan samaa asiaa. Näin määriteltynä ohjelmointirajapinta kattaa sekä web-pohjaiset REST, SOAP tai GraphQL API:t että tiedosto- tai tietokantapohjaisiin tai muihin protokolliin perustuvat rajapinnat. Olennaista on, että ohjelmointirajapinta tarjoaa tietoa tai toiminnallisuutta koneluet- tavassa, dokumentoidussa muodossa siten, että jokin toinen ohjelmisto, sovellus tai järjestelmä voi sitä ohjelmallisesti hyödyntää. Huomioitavaa on se, että ohjelmointirajapinnalla ei tarkoiteta loppukäyttäjille tarkoitet- tuja käyttöliittymärajapintoja, vaan ohjelmointirajapinnan hyödyntäjä on aina jokin toinen ohjelmisto, sovellus, sovelluskomponentti tai järjestelmä. 2.2 Arvoketju Ohjelmointirajapinnat voidaan nähdä omina tuotteinaan, joihin liittyy arvoketju15 (kuva 1). Arvoketju alkaa digitaalisen hyödykkeen tarjoajasta, jolla on hallussaan tuote, digitaa- linen hyödyke, josta on muulle toimijalle arvoa. Digitaalinen hyödyke voi olla esimerkiksi tietoa, kuten tilasto- tai rekisteritietoa tai toiminnallisuutta, kuten veroprosentin laskenta, viitekehysmuunnin tai tietojen ilmoittamistoiminnallisuus. Ohjelmointirajapinnan tarjoaja tarjoaa ohjelmointirajapinnan, jonka kautta muut toi- mijat voivat hyödyntää digitaalisen hyödykkeen tarjoajan tuotetta. Ohjelmointirajapinnan tarjoaja voi olla sama toimija tai eri toimija kuin digitaalisen hyödykkeen tarjoaja. 13 Määritys mukailee Euroopan Unionin julkaisun määritystä, s18–19 (Vaccari, et al., 2020) 14 Tiedonhallintalain 2§, kohta 11 (Tiedonhallintalaki 906/2019, 2019) 15 Arvoketju mukailee Euroopan Unionin julkaisussa esitettyä arvoketjua, s 20 (Vaccari, et al., 2020) 12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Ohjelmointirajapinnan hyödyntäjä hyödyntää rajapintaa ja sen tarjoamaa tietoa tai toi- minnallisuutta omassa sovelluksessaan tai palvelussaan. Ohjelmointirajapinnan hyödyn- täjä voi olla sama tai eri toimija kuin ohjelmointirajapinnan tarjoaja. Sovelluksella tai palvelulla voi olla vielä loppukäyttäjiä. Loppukäyttäjät eivät siis hyö- dynnä suoraan varsinaisia ohjelmointirapintoja, vaan sovellusta tai palvelua, joka hyödyn- tää API:a toiminnassaan. Kuva 1.  API:n arvoketju16 16 Arvoketju mukailee Euroopan Komission julkaisussa esitetty arvoketjua, s20 (Vaccari, et al., 2020). Sovellus tai palvelu joka hyödyntää ohjelmointirajapintaa toiminnassaan. Ohjelmointirajapinta, jonka kautta digitaalisia hyödykkeitä voidaan hyödyntää. Ohjelmointirajapinnan hyödyntäjä Ohjelmointirajapinnan tarjoaja Digitaalisen hyödykkeen tarjoaja Tuotteet Tiedot Toiminnot Toimijat Loppukäyttäjät 13 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 ESIMERKKI • Verohallinnolla on hallussaan tieto henkilöiden veronumeroista ja voimassaolosta17. Verohallinto on digitaalisen hyödykkeen tarjoaja. • Verohallinto on kehittänyt toiminnallisuutta tarjoavan ohjelmointirajapinnan18, jonka kautta muut toimijat voivat tarkistaa ohjelmallisesti, onko jokin veronumero voimassa vai ei. Verohallinto on ohjelmointirajapinnan tarjoaja. • Yksityisen sektorin toimija kehittää tietojärjestelmän, jonka avulla voidaan ylläpitää rakennustyömaille myönnettyjä kulkulupia. Tietojärjestelmä käy uuden kulkuluvan perustamisen yhteydessä varmistamassa, että henkilön veronumero on voimassa Verohallinnon tarjoaman ohjelmointirajapinnan avulla. Yksityisen sektorin toimija on tässä tapauksessa ohjelmointirajapinnan hyödyntäjä. • Rakennusyrityksen työntekijät, esimerkiksi työmaapäälliköt käyttävät tietojärjestelmää kulkulupien hallinnassa. He ovat loppukäyttäjiä. • Verohallinto tarjoaa myös web-käyttöliittymän, jonka avulla veronumeron voi käydä tarkistamassa manuaalisesti esimerkiksi web-selaimen tai mobiililaitteen avulla19. Tässä tapauksessa Verohallinto tarjoaa suoraan loppukäyttäjille suunnattua sovellusta tai palvelua. Mikäli Verohallinto hyödyntää omaa ohjelmointirajapintaansa web-käyttöliittymän veronumeron tarkistuksessa, Verohallinto on myös yksi oman ohjelmointirajapintansa hyödyntäjistä. 17 Verohallinnnon veronumerorekisteri (Verohallinto, 2021d) 18 Veron Vero API (Verohallinto, 2021b) 19 Veron tarjoama web-käyttöliittymä (Verohallinto, 2021c) 14 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 2.3 Tyypitys Ohjelmointirajapinnat voivat olla tyypiltään sisäisiä tai ulkoisia. Taulukossa 1 on esitelty ohjelmointirajapintojen eri tyypit ja niihin liittyvät yleiset ominaisuudet. Taulukko 1.  API-tyypit Ohjelmointirajapinnan tyyppi Käytön rajoitus Potentiaalinen hyödyntäjä Käsiteltävän tiedon luokittelu SISÄINEN Sisäinen API Kyllä Oman organisaation toimijat Turvaluokiteltu tieto Salassa pidettävä tieto ml henkilötieto Julkinen tieto ULKOINEN Kumppani API Kyllä Oman organisaation toimijat Muut julkishallinnon toimijat Muut yksityisen sektorin toimijat Muut toimijat Turvaluokiteltu tieto Salassa pidettävä tieto ml henkilötieto Julkinen tieto Julkinen API Ei Kuka tahansa Julkinen tieto Sisäiset ohjelmointirajapinnat (sisäinen API) ovat vain organisaation omaan käyttöön. Ulkoiset ohjelmointirajapinnat voivat olla rajoitettuja tietyille toimijoille (kumppani API) tai kaikille avoimia rajoittamattomia ohjelmointirajapintoja (julkinen API). Sisäisissä tai ulkoisissa tietyille kumppaneille suunnatuissa ohjelmointirajapinnoissa voi- daan käsitellä julkista tietoa, salassa pidettävää tietoa, henkilötietoa tai turvaluokiteltua tietoa. Julkisissa ohjelmointirajapinnoissa käsitellään vain julkista tietoa. Sisäisissä ja tietyille kumppaneille rajoitetuissa ohjelmointirajapinnoissa yleensä rajapin- nan hyödyntäjä tunnistetaan (autentikoidaan) ja hyödyntäjän käyttöoikeudet tarkistetaan (autorisoidaan). Julkisessa ohjelmointirajapinnassa käyttöoikeuksien tarkistusta (auto- risointia) ei tarvita, koska tarjolla on vain julkista tietoa. Joissain tilanteissa hyödyntäjän tunnistus (autentikointi) voidaan julkisissakin ohjelmointirajapinnoissa tehdä; esimerkiksi jos halutaan kerätä tietoa ohjelmointirajapinnan hyödyntäjistä seurantaa tai viestintää varten. 15 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 ESIMERKKI • Toimijalla, kuten kunnalla, valtion virastolla tai oppilaitoksella, voi olla omia rekistereitä, esimerkiksi asiakasrekisteri tai oppilasrekisteri. Toimija kehittää rekisterin tietojen hakua varten ohjelmointirajapinnan, jonka avulla toimijan muut tietojärjestelmät tai sovellukset voivat hakea ko. rekisteristä tietoja tiettyjen hakukriteerien avulla. Mikäli ohjelmointirajapinta on tarkoitettu vain toimijan omaan käyttöön, on kyseessä sisäinen API. • Maanmittauslaitos tarjoaa kyselypalvelun20, jonka avulla voidaan kysellä rakennuksien tunnistetietoja, ominaisuustietoja sekä omistajatietoa. Palvelun käyttö vaatii Digi- ja väestötietoviranomaisen lupaa ja on näin ollen rajattu tietyille toimijoille. Kyseessä on kumppani API. • Väylävirasto tarjoaa kaikille avoimia rajapintoja21, joiden avulla pääsee lataamaan ja katselemaan tie-, rata-, ja vesiväyläverkkoon liittyviä paikkatietoaineistoja. Kyseessä on julkinen API, jonka käyttö ei vaadi rekisteröitymistä eikä tunnistautumista. 2.4 Elinkaari Ohjelmointirajapinnoilla on elinkaari, joka alkaa siihen liittyvästä tarvekartoituksesta ja päättyy ohjelmointirajapinnan käytöstä poistoon. Elinkaari kattaa kaikki tällä välillä ole- vat vaiheet, joita ovat määrittely ja suunnittelu, kilpailutus ja hankinta, toteutus ja kehitys, käyttöönotto, ylläpito sekä käytöstä poisto22. Ohjelmointirajapinnan elinkaari on iteratiivi- nen, eli vaiheita toistetaan, kunnes ohjelmointirajapinta kaikkine versioineen on poistettu käytöstä. Huomioitavaa on se, että ohjelmointirajapinnan elinkaari voi poiketa tarjoamansa tiedon tai toiminnallisuuden elinkaaresta. Ohjelmointirajapinnan elinkaari voi alkaa vasta myö- hemmin kuin tarjoamansa tiedon tai toiminnallisuuden elinkaari. Voi olla, että tiedon tai toiminnallisuuden elinkaaressa ei tapahdu muutoksia, mutta ohjelmointirajapinnan omi- naisuuksia tai toiminnallisuuksia kehitetään, siitä luodaan uusia versiota ja vanhoja versi- oita poistetaan käytöstä. Ohjelmointirajapinnan elinkaari voi myös päättyä ennen kuin sen tarjoaman tiedon tai toiminnallisuuden elinkaari päättyy esimerkiksi käyttötarpeen päät- tymisen tai teknologian vanhentumisen vuoksi. 20 Maanmittauslaitoksen kyselypalvelu (Maanmittauslaitos, 2021b) 21 Väyläviraston avoimet rajapinnat (Väylävirasto, 2021) 22 Mukailee tietojärjestelmän elinkaarta, s26 (Valtiovarainministeriö, Tiedonhallintalauta- kunta, 2021:65) 16 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 3 Periaatteet Periaatteet on jaettu kolmelle tasolle: strateginen, taktinen ja operatiivinen. Strategisen tason periaatteet ovat kohdistettu organisaation johdolle. Strategisella tasolla kuvataan, miten ohjelmointirajapintojen kehittämiselle tulisi määrittää suunta ja tavoitteet ja miten ohjelmointirajapinnat tulisi huomioida toiminnan kehittämisessä. Taktisen tason periaatteet ovat kohdistettu organisaation tiedonhallintaa kehittäville toi- mijoille. Taktisen tason periaatteet ohjaavat, miten ohjelmointirajapintojen kehittämistä ja ohjelmointirajapintojen muodostamaa kokonaisuutta tulisi hallita. Operatiivisen tason periaatteet ovat kohdistettu ohjelmointirajapintoja kehittäville ja yllä- pitäville toimijoille. Operatiivisen tason periaatteet ohjaavat, miten yksittäisiä ohjelmointi- rajapintoja tulisi kehittää ja ylläpitää. Periaatteet ovat esitelty kappaleissa 3.1, 3.2 ja 3.3. Periaatteet tukevat asetettujen tavoittei- den saavuttamista (kuva 2). Periaatekohtaiset tavoitteet on kuvattu alla olevien symbolien avulla. Kuva 2.  Tavoitteet TAVOITTEET Uudelleenkäytettävyys Yhteentoimivuus Laatu Asiakaslähtöisyys ja yhteistyö Tietoturva ja tietosuoja 17 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 3.1 Strateginen taso Kuva 3.  Strategisen tason periaatteet Määritä ja ota käyttöön tarvittavat yhteistyömenetelmät. Huomioi jo olemassa olevat yhteistyöverkostot ja -foorumit. Määritä omasta organisaatiosta ne henkilöt tai tiimit, joiden tulisi yhteistyötä edistää tai yhteistyöhön osallistua. Tunnista ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen liittyvät sisäiset ja ulkoiset yhteistyötarpeet sekä sidosryhmät. Varmista, että hankittavissa tietojärjest- elmissä on ominaisuudet, jotka mahdollista- vat tietojen tarjoamisen ja hyödyntämisen avointen ja teknologiariippumattomien ohjelmointirajapintojen kautta. Hanki tavoitteiden saavuttamista varten tarvittavat resurssit kuten henkilö- ja teknologiaresurssit sekä rahoitus. Ohjelmointirajapintojen kehittämisen mittarit. Määritä ohjelmointirajapintojen tarjoamiselle ja hyödyntämiselle tavoitteet ja mittarit. Huomioi organisaation strategia, koko ja kyvykkyydet sekä muut tiedonhallinnan tavoitteet. 1.2 Määritä ohjelmointirajapintojen tarjoamiselle ja hyödyntämiselle tavoitteet ja mittarit sekä hanki riittävät resurssit. Määritä mitä tietoaineistoja ja toiminnallisuuk- sia tarjotaan tai hyödynnetään ohjelmointira- japintojen avulla sisäisesti ja ulkoisesti. Tunnista organisaatiosi toimintaprosessien kannalta tärkeät tietoaineistot ja toiminnallisuu- det sekä niiden tuoma hyötypotentiaali. 3 4 5 6 7 8 1.4 Edistä sisäistä ja ulkoista yhteistyötä. 1.3 Varmista hankinnoissa yhteentoimivuus muiden tietojärjestelmien kanssa. 1.1 Tarjoa ja hyödynnä tietoja pääsääntöisesti ohjelmointirajapintojen kautta. TA VO IT TE ET 1 2 Listaus rajapintojen kautta tarjottavista tai hyödynnet- tävistä tietoaineistoista. Listaus rajapintojen kautta tarjottavista tai hyödynnettävistä toiminnallisuuksista. Ohjelmointirajapintojen kehittämisen tavoitteet. Resurssisuunnitelma. Ohjelmointirajapintojen vaatimukset osana hankinnan kohteen kuvausta. Suunnitelma yhteistyöstä sisältäen sisäiset ja ulkoiset sidosryhmät ja yhteistyömenetelmät. Yhteistyön tuotokset: esim. tunnistetut tarpeet, jaetut ratkaisut. 18 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Periaate 1.1 Tarjoa ja hyödynnä tietoja pääsääntöisesti ohjelmointirajapintojen kautta Tunnista organisaatiosi toimintaprosessien ja ydintehtävien kannalta tärkeät tieto- aineistot ja toiminnallisuudet, joita voidaan tarjota tai hyödyntää ohjelmointiraja- pintojen avulla. Tunnista myös niiden tuoma hyötypotentiaali. Huomioi, että tietoai- neistot tai toiminnallisuudet voivat olla omia tai muiden toimijoiden. Tietoaineistojen ja toiminnallisuuksien hyötypotentiaali voi liittyä organisaation oman tai sidosryhmien toi- minnan kehittämiseen tai tarpeeseen. Ohjelmointirajapintojen kautta tarjottavia tai hyödynnettäviä tietoaineistoja tai toiminnal- lisuuksia voi määrittää esimerkiksi seuraavien kysymysten kautta: y Mitä tietoa tai toiminnallisuuksia organisaatiollasi on saatavilla? y Mitä tai millaista tietoa tarvitaan lisää? y Millainen tieto tukee tiedolla johtamista? y Mitkä ovat sidosryhmien tietojen tai toiminnallisuuksien tarpeet? y Mitä tietoa tarvitaan säännöllisesti, koneluettavassa muodossa tai mahdolli- simman ajantasaisena? y Mitä toiminnallisuuksia olisi tarpeen tai mahdollista tarjota tai hyödyntää digitaalisesti? y Pohdi myös millaisia hyötyjä, riskejä ja kustannuksia tietojen tai toiminnalli- suuksien tarjoaminen ja hyödyntäminen aiheuttavat organisaatiollesi. Määritä mitä tai millaisia tietoaineistoja tai toiminnallisuuksia voidaan tarjota tai hyödyntää ohjelmointirajapintojen avulla sisäisesti ja ulkoisesti. Tunnista tietojen tai toiminnallisuuksien hallinnoijat. Sisäinen tarjoaminen ja hyödyntäminen voidaan tehdä sisäisten rajapintojen (sisäinen API) avulla. Ulkoinen tarjoaminen ja hyödyntäminen voi- daan tehdä kumppanirajapintojen (kumppani API) tai julkisten rajapintojen (julkinen API) avulla tiedon luokituksen mukaan. Julkiset rajapinnat voivat luoda uudenlaisia toiminta- tapoja, tuotoksia ja kumppanuuksia ja vaikuttaa siten merkittävästikin organisaatioiden toimintaan. Huomioi tietojen saantioikeuksista, tietojen luovutuksista ja tietojen tarjoamisesta koneel- lisesti luettavassa muodossa säädetyt lait ja niiden asettamat velvoitteet23. On tärkeä myös tunnistaa ne tiedot, jotka ovat salassa pidettäviä. Huomioi myös tietoaineistoille mahdolli- sesti tarvittavat muokkaukset kuten pseudonymisointi tai anonymisointi24. 23 Esimerkiksi Tiedonhallintalain 22§ (Tiedonhallintalaki 906/2019, 2019) ja Tiedonhallinta- lautakunnan suositus teknisistä rajapinnoista ja katseluyhteyksistä (Valtiovarainministeriö, Tiedonhallintalautakunta, 2021:21). 24 Pseudonymisoidut ja anonymisoidut tiedot -sivusto (Tietosuojavaltuutetun toimisto, 2021). Tutustu myös Kyberturvallisuuskeskuksen Tunnisteet ja tietosuoja, anonymisointi ja sen rajat -oppaaseen (Traficom, Kyberturvallisuuskeskus 2021) 19 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUOTOKSET • Listaus mahdollisesti rajapintojen kautta tarjottavista tai hyödynnettävistä tietoaineistoista. • Listaus mahdollisesti rajapintojen kautta tarjottavista tai hyödynnettävistä toiminnallisuuksista. HYÖDYT • Listausten avulla organisaation on helpompi tunnistaa ja kohdentaa rajapintakehittämistä hyötypotentiaalia omaaviin tietoaineistoihin ja toiminnallisuuksiin ja edistää sitä kautta tarvelähtöistä rajapintakehittämistä. • Kohdennetulla ja tarvelähtöisellä kehittämisellä edistetään rajapintojen asiakaslähtöisyyttä ja yhteistyötä, uudelleenkäytettävyyttä, yhteentoimivuutta ja laatua. 20 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUKIMATERIAALI Esimerkkejä tietoa tai toiminnallisuutta tarjoavista ohjelmointirajapinnoista: • Helsingin kaupunki on avannut palauterajapinnan25, jonka avulla voi antaa Helsingin kaupungille palautetta, kuten ilmoittaa rikkoutuneesta liikennemerkistä tai kuopista teissä ja lisäksi hakea järjestelmässä julkaistuja palautteita. Kyseessä on sekä toiminnallisuutta, palautteen antamista että tietoa tarjoava rajapinta. • Finna tarjoaa avoimen rajapinnan26, jonka avulla voi kohdistaa hakuja suomalaisten kirjastojen, arkistojen ja museoiden aineistoihin. Kyseessä on tietoa tarjoava rajapinta. Tutustu myös seuraaviin aineistoihin, joista voit saada apua ohjelmointirajapintojen kautta tarjottavien tai hyödynnettävien tietojen ja toiminnallisuuksien tunnistamiseen ja hyötypotentiaalin arvioimiseen: • Tiedonhallintalautakunnan julkaisema Suositus tiedonhallintamallista27. • Arviointimenetelmä hyötypotentiaalisten tietojen tunnistamiseen (hyödyt, riskit ja kustannukset) ja jakamiseen28. • Tiedonhallintakartta julkisen hallinnon yhteisten tietovarantojen lakisääteisten tietojen luovutusten nykytilan tunnistamiseen29. Periaate 1.2 Määritä ohjelmointirajapintojen tarjoamiselle ja hyödyntämiselle tavoitteet ja mittarit sekä hanki riittävät resurssit Määritä ohjelmointirajapintojen tarjoamiselle ja hyödyntämiselle tavoitteet. Tavoitteiden tulee palvella organisaation strategiaa, toimintaprosesseja ja nii- den tulee olla linjassa muun tiedonhallinnan tavoitteiden kanssa. Tavoitteiden tulee olla realistisia organisaation kokoon ja kyvykkyyksiin nähden. Tavoitteet voidaan kuvata 25 Helsingin kaupungin palauterajapinta (Helsingin kaupunginkanslia, 2020), tutustu myös 6Aika hankkeen tekemään määritelmään palauterajapinnasta (6Aika-kaupungit, 2016) 26 Finnan avoin rajapinta (Kansalliskirjasto, Finna, 2021) 27 Suositus Tiedonhallintamallista (Valtiovarainministeriö, Tiedonhallintalautakunta, 2020:29) 28 Arviointimenetelmä julkaistaan maaliskuussa 2022 Digi- ja väestötietoviraston ylläpitä- mässä avoindata.fi -palvelussa. 29 Julkisen hallinnon tiedonhallintakartta tutkihallintoa.fi -palvelussa (Valtiovarainministe- riö, 2022) https://www.avoindata.fi/data/fi/dataset/helsingin-kaupungin-palauterajapinta https://www.kiwi.fi/display/Finna/Finnan+avoin+rajapinta https://julkaisut.valtioneuvosto.fi/bitstream/handle/10024/162176/VM_2020_29.pdf?sequence=1&isAllowed=y https://www.tutkihallintoa.fi/tiedonhallintakartta/ 21 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 esimerkiksi osana muita tiedonhallinnan tavoitteita tai datastrategiaa tai erillisessä API- tai integraatiostrategiassa. Määritä ohjelmointirajapintojen tarjoamiselle ja hyödyntämiselle tarvittavat mitta- rit. Mittarit voivat olla prosessi-, tulos- tai vaikuttavuusmittareita30 (katso kuva 4). Prosessi- mittarien avulla ohjataan toimintaa tai varmistetaan toiminnan laatua, esimerkiksi palve- lutason toteutumista. Tulosmittareilla mitataan yleensä jonkin muutoksen suuntaa ja suu- ruutta, esimerkiksi ohjelmointirajapinnoille asetettujen tavoitteiden saavuttamista. Vaikut- tavuusmittarit kertovat toiminnan tuloksista suhteessa yhteiskunnalliseen päämäärään, ongelmaan tai tarpeeseen, esimerkiksi ohjelmointirajapintojen vaikutusta julkisen hallin- non palveluiden kehittymiseen tai tiedolla johtamiseen. Valitse sellaiset mittarit, jotka pal- velevat organisaatiosi seurannan tarpeita ja joita on mahdollista seurata. Mittareita voi- daan seurata organisaation eri tasoilla: strategisella, taktisella ja operatiivisella. Hanki tavoitteiden saavuttamista varten tarvittavat resurssit. Huomioi resursseissa sekä ohjelmointirajapintojen tarjoaminen ja hyödyntäminen että ylläpitäminen. Resurssit voivat olla esimerkiksi henkilöresursseja, oikeanlaista osaamista tai tekno- logisia resursseja. Resurssien ja osaamisen hankkiminen ja ylläpitäminen vaativat rahoi- tusta. Käy keskustelua organisaation tiedonhallinnasta vastaavien tiimien tai henkilöiden kanssa osaamis-, resurssi- ja rahoitustarpeista niiden tunnistamista ja hankkimista varten. Kehitä mahdollisuuksien mukaan oman organisaatiosi henkilöstön osaamista. Hyödynnä jo olemassa olevia tiedonhallinnan, kokonaisarkkitehtuurin, sovelluskehityksen tai inte- graatioiden parissa työskenteleviä tiimejä tai henkilöitä. Kuvassa 4 on esimerkki ohjelmointirajapintojen kehittämiselle asetetuista tavoitteista, mit- tareista ja tarvittavista resursseista. Esimerkkikuvassa ohjelmointirajapintojen kehittämi- sen tavoitteet on johdettu kuvitteellisen organisaation strategisista tavoitteista. 30 Mittareiden valinta (Hyvän Mitta, 2021) 22 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Kuva 4.  Esimerkki tavoitteista, mittareista ja resursseista Tarvittavat resurssit Pitkällä aikavälillä ohjelmointi- rajapintojen tarjoamisen tai hyödyntämisen kerrannaisvai- kutukset. Mittaavat muutoksen suuntaa ja suuruutta – tässä tapauksessa tavoitteiden saavuttamista. Ohjaavat toimintaa ja varmistavat toiminnan laatua. Tavoitteet voidaan määrittää esimerkiksi osana tiedonhallinnan tavoitteita tai datastrategiaa. Tavoitteet ohjelmointirajapintojen kehittämiselle Organisaation strategiset tavoitteet TulosmittaritProsessimittarit Vaikuttavuusmittarit Tunnista tavoitteiden saavuttamiseen vaadittavat resurssit. Rahoitus Teknologiaresurssit Kehitämme tiedolla johtamista. Tarjoamme laadukkaita ja turvallisia sähköisiä palvelukanavia kansalaisille. Teemme aktiivista yhteistyötä toisten viranomaisten kanssa. Otamme julkisen hallinnon API-periaatteet käyttöön. Otamme käyttöön ohjelmointirajapinto- jen julkaisualustan laadukkaiden ja turvallisten ohjelmointirajapinto- jen tarjoamiseksi. Tarjoamme organisaa- tion keskeisimmät tiedot ja toiminnal- lisuudet ohjelmointira- japintojen avulla uudelleenkäytettäviksi. Teemme yhteistyötä ja jaamme API-kehity- sosaamista ja kokemuksia muiden viranomaisten kanssa. Kehittämis- ja ylläpitokustannukset. API:en ja API:en hyödyntäjien määrät. API:en palvelutaso ja vasteajat. Resurssien käyttö (CPU, muisti). Virhetilanteiden ja poikkeamien määrät. Hyödyntäjätyytyväisyys CSAT asteikko 1–5. Uuden julkaisualustan valmiusaste %. API-periaatteiden toimeen- panon valmiusaste %. API:en määrä uudella julkaisualustalla. API:en kautta julkaistujen tietovarantojen määrä. API:en kautta julkaistujen toiminnallisuuksien määrä. Yhteistyötapaamisten määrä. Digitaalisesti saatavilla olevien palveluiden määrä (määrän muutos). Digitaalisten palveluiden hyödyntäjien määrä (määrän muutos). Tyytyväisyys digitaalisiin palveluihin (tyytyväisyyden muutos). Henkilöresurssit ja osaaminen 23 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUOTOKSET • Ohjelmointirajapintojen kehittämisen tavoitteet. Voivat olla esimerkiksi osana tiedonhallinnan tavoitteita, datastrategiaa tai integraatiostrategiaa. • Ohjelmointirajapintojen kehittämisen mittarit, jotka palvelevat organisaation seurannan tarpeita ja joita on mahdollista seurata. • Resurssisuunnitelma tavoitteiden saavuttamista varten huomioiden henkilö- ja teknologiaresurssit sekä rahoituksen. HYÖDYT • Tavoitteiden asettamisen ja resurssisuunnitelman avulla organisaatio voi vaiheistaa ja priorisoida rajapintakehitystään ja kohdentaa resursseja kehitykseen, jolloin kehittäminen tapahtuu hallitusti, suunnitelmallisesti ja palvelee organisaation muita tavoitteita. • Erilaisten mittareiden avulla organisaatio voi seurata ohjelmointirajapintojen kehityksessä tapahtunutta muutosta ja asetettujen tavoitteiden saavuttamista. • Hallitulla ja suunnitelmallisella kehityksellä ja seurannalla edistetään rajapintojen uudelleenkäytettävyyttä, yhteentoimivuutta, tietoturvan ja tietosuojan huomioimista sekä laatua. 24 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUKIMATERIAALI Esimerkkejä ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen liittyvistä tavoitteista ja tavoitteiden suhteuttamisesta organisaation muuhun strategiaan: • Helsingin kaupungin datastrategia31, joka ottaa kantaa tietojen tarjoamiseen ja hyödyntämiseen ohjelmointirajapintojen avulla. • API-kehittäminen Verolla32, joka esittelee ohjelmointirajapinnat Verohallinnon strategiassa. • API:t osana valtioneuvoston periaatepäätöksen tiedon hyödyntämiseksi ja avaamiseksi strategisia tavoitteita.33 Tutustu myös seuraaviin aineistoihin, joista voit saada apua tavoitteiden ja mittareiden tunnistamista varten: • Hyvän Mitta - hanke34, sisältää lisätietoa vaikuttavuudesta, vaikuttavuusketjusta ja mittarien valinnasta. • Metropolian opinnäytetyö: Strategisten tavoitteiden toteutumisen mittaaminen35, sisältää mm. ”hyvän mittarin tunnusmerkit” -tarkastuslistan ja tietotekniikkaohjelmiston mittaristoesimerkin. Periaate 1.3 Varmista hankinnoissa yhteentoimivuus muiden tietojärjestelmien kanssa Varmista, että hankittavissa tietojärjestelmissä on ominaisuudet, jotka mahdollista- vat tietojen tarjoamisen ja hyödyntämisen avointen ja teknologiariippumattomien ohjelmointirajapintojen kautta. Tarvittavia ominaisuuksia ovat esimerkiksi: y Valmisohjelmiston tarjoamat valmiit ohjelmointirajapinnat, joiden avulla voi- daan tarjota järjestelmän sisältämiä tietoja tai toiminnallisuuksia muille järjes- telmille. Ohjelmointirajapintojen tulisi perustua avoimiin, teknologiariippu- mattomiin ja yleisesti käytössä oleviin protokolliin ja standardeihin. 31 Helsingin kaupungin datastrategia, luku 5 (Digitaalinen Helsinki, 2021) 32 Veron API-kehittäminen (Verohallinto, 2019) 33 Valtioneuvoston periaatepäätös tiedon hyödyntämiseksi ja avaamiseksi on tarkoitus jul- kaista kevään 2022 aikana. 34 Hyvän Mitta (Hyvän Mitta, 2021) 35 Strategisten tavoitteiden toteutumisen mittaaminen (Rautio, 2015) https://digi.hel.fi/esittely/helsinki-datastrategia http://131.207.14.19/contentassets/5389e8bf012445db8fb5865ad0fe745e/10.-api-kehitt%C3%A4minen_verolla.pdf https://www.hyvanmitta.fi/ https://www.theseus.fi/handle/10024/89635 https://www.theseus.fi/handle/10024/89635 25 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 y Välineet, joiden avulla voidaan kehittää kokonaan uusia rajapintoja tai muo- kata valmiita rajapintoja paremmin tarkoitukseen soveltuviksi. y Välineet, joiden avulla voidaan integroida järjestelmä muiden järjestelmien tarjoamiin rajapintoihin. y Lisensointimalli tai -ehdot, jotka mahdollistavat järjestelmän tietojen ja toi- minnallisuuksien tarjoamisen, hyödyntämisen ja uudelleenkäyttämisen orga- nisaation sisäisesti sisäisten rajapintojen (sisäinen API) että ulkoisesti ulkois- ten rajapintojen (kumppani API, julkinen API) avulla. y Käyttöoikeuksien ja käyttötarkoituksen hallinta salassa pidettävien, tur- vallisuusluokiteltujen ja henkilötietojen vaatimusten mukaisuuden varmistamiseksi. Tietojärjestelmähankinnoissa tietojen ja toiminnallisuuksien tarjoamiseen ja hyödyntä- miseen liittyvät vaatimukset pitää sisällyttää jo tarjouspyynnössä osaksi hankitta- van kohteen määrittelyä36. Organisaation tietohallinnon on tärkeää olla alusta alkaen mukana uusissa tietojärjestelmähankinnoissa. TUOTOKSET • Ohjelmointirajapintojen vaatimukset osana hankinnan kohteen kuvausta. HYÖDYT • Huomioimalla tietojen ja toiminnallisuuksien tarjoamiseen ja hyödyntämiseen liittyvät vaatimukset jo tietojärjestelmien hankintavaiheessa mahdollistetaan tietojärjestelmän yhteensovittaminen organisaation nykyiseen tietojenkäsittely-ympäristöön ja siihen jatkossa tuleviin muutoksiin. • Lisäksi avoimet, teknologiariippumattomat ja yleisesti käytössä protokollat ja standardit sekä joustava lisensointimalli vähentävät mahdollisen toimittajalukon riskiä. • Tietojärjestelmät, jotka kykenevät tarjoamaan ja hyödyntämään avoimia, teknologiariippumattomia ja yleisesti käytössä olevia ohjelmointirajapintoja edistävät niiden uudelleenkäytettävyyttä sekä teknistä yhteentoimivuutta. 36 Hankintalaki (Laki julkisista hankinnoista ja käyttöoikeussopimuksista 1397/2016, 2016). 26 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUKIMATERIAALI Tukea ja lisätietoa hankintoihin liittyen saa esimerkiksi: • Julkisten hankintojen neuvontayksikön verkkopalvelusta37. • HANSEL:in ylläpitämistä yhteishankintamateriaaleista38. • Tiedonhallintalautakunnan suosituskokoelmasta tiettyjen tietoturvallisuussäännösten soveltamisesta39, jossa otetaan kantaa tiedon elinkaaren huomioimisesta tietojärjestelmissä mukaan lukien kilpailutus- ja hankintavaihe. Periaate 1.4 Edistä sisäistä ja ulkoista yhteistyötä Tunnista ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen liittyvät sisäiset ja ulkoiset yhteistyötarpeet. Yhteistyötarpeet voivat liittyä esimerkiksi: y Ideoiden tai tarpeiden tunnistamiseen tai jakamiseen. y Tavoitteiden, toimintamallien, ohjeiden tai ohjeistusten kehittämiseen tai jakamiseen. y Ratkaisuiden kehittämiseen tai jakamiseen. y Osaamisen tai kokemusten jakamiseen. Tunnista sidosryhmät, joiden kanssa yhteistyötä tulisi tehdä. Huomioi, että yhteis- työtä tehdään organisaatioiden eri tasoilla. Sidosryhmiä ovat esimerkiksi: y Oman tai muun organisaation johto. y Oman tai muun organisaation tiedonhallintaa kehittävät henkilöt tai tiimit. y Oman tai muun organisaation kehitys- ja ylläpitotiimit. Määritä omasta organisaatiosta ne henkilöt tai tiimit, joiden tulisi yhteistyötä edis- tää tai yhteistyöhön osallistua. Pohdi yhdessä heidän kanssaan minkälaisella yhteistyö- rakenteella voisitte edistää ja tehostaa tiedon ja toiminnallisuuksien hyödyntämistä niin organisaation sisällä kuin ulkopuolella rajapintojen kautta. Pienissä organisaatioissa tämä 37 Julkisten hankintojen neuvontayksikkö (Julkisten hankintojen neuvontayksikkö, 2021) 38 Yhteishankinnat (Hansel, 2021) 39 Tiedonhallintalautakunnan suosituskokoelma tiettyjen tietoturvallisuussäännösten soveltamisesta (Valtiovarainministeriö, Tiedonhallintalautakunta, 2021:65) https://www.hankinnat.fi/ https://www.hansel.fi/yhteishankinnat/ https://julkaisut.valtioneuvosto.fi/handle/10024/163596 https://julkaisut.valtioneuvosto.fi/handle/10024/163596 27 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 voi tarkoittaa vain paria henkilöä, jolloin on erityisesti syytä tehdä yhteistyötä ja jakaa kehittäjäkokemuksia verkostoissa. Määritä ja ota käyttöön tarvittavat yhteistyömenetelmät. Huomioi jo olemassa olevat yhteistyöverkostot ja –foorumit. TUOTOKSET • Suunnitelma yhteistyöstä sisältäen sisäiset ja ulkoiset sidosryhmät ja yhteistyömenetelmät. • Yhteistyön tuotokset, esimerkiksi tunnistetut tarpeet, jaetut ratkaisut tai kokemukset sekä osaamisen kehittyminen. HYÖDYT • Verkostoitumisen, yhteistyön ja jatkuvan keskustelun avulla kyetään tunnistamaan organisaatioiden sisäisten ja ulkoisten sidosryhmien muuttuvia tarpeita ja kehittämään tarpeisiin vastaavia ohjelmointirajapintoja. • Lisäksi yhteistyö mahdollistaa osaamisen jakamisen yli organisaatiorajojen, kun jo saatuja oppeja, kokemuksia ja ratkaisuja jaetaan eri toimijoiden kesken. • Sidosryhmien tarpeiden tunnistaminen edistää ohjelmointirajapintojen asiakaslähtöisyyttä ja yhteistyötä, uudelleenkäytettävyyttä, yhteentoimivuutta ja laatua. 28 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUKIMATERIAALI Esimerkkejä olemassa olevista yhteistyöfoorumeista, joihin organisaation henkilöstö voi liittyä: • Avoimen tiedon verkosto40 • Maanmittauslaitoksen yhteistyöryhmät41 • Verkkolaskufoorumi42 • API-Suomi Facebook-ryhmä43 • Github-yhteisöt44 • Suomen standardisoimisliitto SFS Ry:n tieto-ja viestintätekniikan standardisointiryhmät45. 40 Avoimen tiedon verkosto (Varsinais-Suomen liitto, 2021) 41 Maanmittauslaitoksen yhteistyöryhmät (Maanmittauslaitos, 2021c) 42 Verkkolaskufoorumi (TIEKE Tietoyhteiskunna Kehittämiskeskus Ry, 2021) 43 API-Suomi Facebook-ryhmä (Honkanen, 2021) 44 GIT-hubin yhteisöt (GitHub, 2021) 45 Tieto -ja viestintätekniikan standardisointiryhmät (Suomen standardisoimisliitto SFS Ry, 2021b) https://kumppanuusfoorumi.fi/foorumi/avoimen-tiedon-verkosto/ https://www.maanmittauslaitos.fi/tietoa-maanmittauslaitoksesta/organisaatio/yhteistyoryhmat https://tieke.fi/palvelut/liiketoimintapalvelut/verkkolaskufoorumi/ https://fi-fi.facebook.com/groups/apisuomi/ https://github.com/ https://sfs.fi/osallistu-ja-vaikuta/aihealueet/tieto-ja-viestintatekniikka/ https://sfs.fi/osallistu-ja-vaikuta/aihealueet/tieto-ja-viestintatekniikka/ 29 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 3.2 Taktinen taso Kuva 5.  Taktisen tason periaatteet 1 2 6 4 5 7 2.1 Kehitä ohjelmointirajapintoja tarvelähtöisesti. 2.3 Kuvaa ohjelmointirajapintojen muodostama kokonaisuus. 2.4 Tunnista ja hallitse ohjelmointirajapintoihin liittyvät riskit. TA VO IT TE ET 3 Tunnista ohjelmointirajapintoihin liittyvät sisäiset ja ulkoiset sidosryhmät ja kerää heiltä tarpeita ja vaatimuksia. Priorisoitu lista tarpeista ja kehityskohteista, esimerkiksi kehitysjono (backlog).Priorisoi ja kehitä ohjelmointirajapintoihin liittyviä ominaisuuksia tarpeiden perusteella. Tiedota ohjelmointirajapintojen sidosryhmiä ohjelmointirajapintoihin liittyvästä kehityksestä. Sisäisen ja ulkoisen viestinnän materiaalit. 2.2 Määritä ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen liittyvät roolit, tehtävät, vastuut ja toimintamallit. Määritä ja ota käyttöön ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen liittyvät roolit, tehtävät ja vastuut. Roolien, tehtävien ja vastuiden kuvaukset ja vastuutukset. Määritä ja ota käyttöön ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen tarvittavat toimintamallit tai prosessit kuten suunnittelu-, kehitys-, testaus-, julkaisu- ja ylläpitoprosessit. Prosessi - ja/tai toimintamallikuvaukset. Määritä ja ota käyttöön ohjelmointirajapintojen muodostamalle kokonaisuudelle kuvaustapa, huomioi eri arkkitehtuurinäkökulmat sekä linkitys tiedonhallintamalliiin. Ohjelmointirajapintojen kuvaukset esimerkiksi osana tiedonhallintamallia. Määritä ja ota käyttöön menetelmä ohjelmointi- rajapintoihin liittyvien riskien ja uhkien tunnista- miseen sekä riskienhallintatoimenpiteiden toteuttamiseen ja seurantaan. Huomioi myös lakisääteiset vaatimukset tietojen käsittelylle. Riskirekisteri. Riskienhallintatoimenpiteet. 30 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Periaate 2.1 Kehitä ohjelmointirajapintoja tarvelähtöisesti Tunnista ohjelmointirajapintoihin liittyvät sisäiset ja ulkoiset sidosryhmät ja kerää heiltä tarpeita ja vaatimuksia. Sidosryhmiä ovat esimerkiksi: y Arvoketjuun liittyvät toimijat, kuten digitaalisen hyödykkeen tarjoaja, ohjel- mointirajapinnan tarjoaja sekä ohjelmointirajapinnan hyödyntäjä tai potenti- aalinen hyödyntäjä. y Oman tai muun toimijan tiedonhallinnan parissa työskentelevät henkilöt, tii- mit tai ryhmät, johto, suunnittelijat, kehittäjät, testaajat tai ylläpitäjät. Tarpeet voivat liittyä rajapintojen toiminnallisuuksiin tai ei-toiminnallisuuksiin kuten saatavuuteen, käytettävyyteen, tiedon eheyteen, palvelutasoon tai kehittäjä- tai loppukäyttäjäkokemukseen. Huomioi myös lainsäädännöstä tulevat vaatimuk- set46 ja lainsäädännössä tapahtuvat muutokset. Tarpeita voidaan kerätä muun muassa hyödyntämällä kyselyitä, palautekanavia, yhteistyöryhmiä, työpajoja tai muita yhteistyö- menetelmiä. Jos kyseessä on julkinen tai avoimen datan rajapinta, jonka hyödyntäjiä ei kyetä tunnistamaan, saattaa tarpeiden keruu hyödyntäjiltä tai potentiaalisilta hyödyntä- jiltä olla hankalaa. Tällaisessakin tapauksessa voidaan esimerkiksi julkaista avoin palaute- kanava hyödyntäjiä varten. Priorisoi ja kehitä ohjelmointirajapintoihin liittyviä ominaisuuksia tarpeiden perus- teella. Huomioi tarpeet ohjelmointirajapintojen koko elinkaaren ajan aina tarvekartoituk- sesta käytöstä poistoon asti: määrittele ja suunnittele, kilpailuta ja hanki, toteuta ja kehitä, käyttöönota, ylläpidä ja poista ohjelmointirajapintoihin liittyviä ominaisuuksia tarpeiden ja vaatimusten mukaisesti. Tiedota ohjelmointirajapintojen sidosryhmiä ohjelmointirajapintoihin liittyvästä kehityksestä. Huomioi viestinnässä sekä organisaation sisäiset että ulkoiset sidosryhmät. 46 Esimerkiksi tiedonhallintalain vaatimus toistuvan ja vakiosisältöisen sähköisen tietojen luovutuksesta teknisen rajapinnan avulla (Tiedonhallintalaki 906/2019, 2019) sekä turval- lisuusluokiteltujen asiakirjojen käsittelylle asetetut lakivaatimukset (Valtioneuvoston ase- tus asiakirjojen turvallisuusluokittelusta valtionhallinnossa, 1101/2019). Tutustu myös tie- donhallintalautakunnan suosituksiin (Valtiovarainministeriö, Tiedonhallintalautakunta, 2020–2021). 31 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUOTOKSET • Priorisoitu lista ohjelmointirajapintoihin liittyvistä tarpeista ja kehityskohteista, esimerkiksi kehitysjono (backlog). • Sisäisen ja ulkoisen viestinnän materiaalit. HYÖDYT • Tarpeiden kerääminen ja tunnistaminen auttavat kohdistamaan ohjelmointirajapintojen kehitykseen tarvittavat resurssit ja toimenpiteet tehokkaasti niiden tarpeiden täyttämiseen, joista on eniten hyötyä niin organisaatiolle itselleen kuin ohjelmointirajapintojen hyödyntäjille. • Ohjelmointirajapintojen kehittämisestä tiedottaminen antaa sidosryhmille mahdollisuuden reagoida ajoissa tuleviin muutoksiin sekä suunnitella omaa toimintaansa huomioiden suunnitteilla olevat kehityskohteet. • Oikein kohdistetut resurssit, hyödylliset ja tarpeet täyttävät ohjelmointirajapinnat sekä aktiivinen viestintä edistävät ohjelmointirajapintojen asiakaslähtöisyyttä ja yhteistyötä, uudelleenkäytettävyyttä, yhteentoimivuutta ja laatua. TUKIMATERIAALI Esimerkkejä julkisen hallinnon organisaatioiden julkaisemista avoimista kanavista, joiden kautta kyetään keräämään tarpeita sidosryhmiltä tai viestimään sidosryhmille: • Digitraffic-sivusto47, jonka kautta pääsee näkemään rajapintojen tiloja ja rajapintoihin liittyviä tiedotteita. Lisäksi sivuilta on linkitys avoimiin Google-keskusteluryhmiin, joissa mm. tiedotetaan rajapintojen kehityksestä ja käyttökatkoista. • Vero API -sivusto48, joka tarjoaa muun muassa katsauksen suunnitteilla oleviin rajapintoihin sekä havaintolomakkeen, jonka avulla ohjelmointirajapintojen hyödyntäjät voivat antaa palautetta tai kehitysideoita Verohallinnolle. 47 Liikenteen avoin data ja rajapinnat (Fintraffic, 2021) 48 Vero API (Verohallinto, 2021b) https://www.digitraffic.fi/ https://www.vero.fi/tietoa-verohallinnosta/kehittaja/veron-rajapintapalvelut/vero-api/ 32 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Periaate 2.2 Määritä ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen liittyvät roolit, tehtävät, vastuut ja toimintamallit Määritä ja ota käyttöön ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen liittyvät roolit, tehtävät ja vastuut. Huomioi ohjelmointirajapintakonaisuuden hallintaan liittyvät tehtävät kuten tiedonhallintamallin ylläpito, riskienhallinta ja arkkitehtuuriohjaus sekä ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen liittyvät tehtävät sekä ohjel- mointirajapinnassa käsiteltävien tietojen hallintavastuut. Hyödynnä mahdollisuuksien mukaan organisaatiossa jo olemassa olevia rakenteita ja hyviä käytäntöjä. Ohjelmointira- japintojen hyödyntäminen tarkoittaa käytännössä integraatiota johonkin ohjelmointiraja- pintaan. Ohjelmointirajapinnoilla ja integraatioilla on elinkaari, joten tehtävissä tulee huo- mioida elinkaaren eri vaiheet: y Ohjelmointirajapinnan tai integraation tarpeiden kartoitus ja priorisointi. y Ohjelmointirajapinnan tai integraation määrittely ja suunnittelu, tietoturva ja tietosuoja huomioiden. y Ohjelmointirajapintaan tai integraatioon liittyvät kilpailutukset ja hankinnat. y Ohjelmointirajapinnan tai integraation toteutus ja kehitys. y Ohjelmointirajapinnan tai integraation käyttöönotto. y Ohjelmointirajapinnan tai integraation ylläpito ja tuki. y Ohjelmointirajapinnan tai integraation käytöstä poisto. Osa ohjelmointirajapinnan elinkaareen liittyvistä tehtävistä voidaan ulkoistaa; esimer- kiksi ohjelmointirajapintojen toteutusta ja kehitystä tai ylläpitoa ja tukea voidaan ulkoistaa kumppaneille. Huomioi rooli-, vastuu- ja tehtäväkuvauksissa oman organisaatiosi ja kump- paniesi roolit, tehtävät ja vastuut. Määritä ja ota käyttöön ohjelmointirajapintojen tarjoamiseen ja hyödyntämiseen tarvittavat toimintamallit tai prosessit, kuten suunnittelu-, kehitys-, testaus-, julkaisu- ja ylläpitoprosessit. Huomio toimintamallien ja prosessien kuvaamisessa oman organisaa- tion lisäksi myös toimintamalliin tai prosessiin keskeisesti liittyvät muut julkiset ja yksityi- set organisaatiot. Kuva 6 sisältää yhdenlaisen esimerkin API-arvoketjun eri toimijoista, toimijoiden rooleista, tehtävistä ja vastuista huomioiden sekä ohjelmointirajapintojen kokonaisuuden hallinnan että ohjelmointirajapintojen tarjoamisen ja hyödyntämisen. Esimerkin on tarkoitus aut- taa hahmottamaan rooleja, tehtäviä ja vastuita paremmin. Isossa organisaatiossa tehtä- viä voidaan allokoida eri henkilöille ja tiimeille. Pienessä organisaatiossa voi olla niin, että yksittäisille henkilöille tulee useita esimerkkikuvassa näkyvien tiimien tai roolien tehtä- viä. Toimintamalleja miettiessä avainasemassa on organisaation koko ja jo olemassa oleva organisaatiorakenne. 33 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Kuva 6.  Esimerkki toimijoista, rooleista ja vastuista Tarjottavan tiedon tai toiminnallisuuden kehittäminen ja ylläpito. Digitaalisen hyödykkeen tarjoaja Loppukäyttäjät Loppukäyttäjät Tiedot Toiminnallisuudet Sovellus Integraatioiden tarvekartoitus, määrittely ja suunnittelu, tarvittavat kilpailutukset ja hankinnat, toteutus ja kehitys, käyttöönotto, ylläpito sekä käytöstä poisto. Ohjelmointirajapinnan tarvekartoitus, määrittely ja suunnittelu, tarvittavat kilpailutukset ja hankinnat, toteutus ja kehitys, käyttöönotto, ylläpito sekä käytöstä poisto. Tiedon tai toiminnallisuuden hallinnoija - Hallinnoi ja priorisoi tietoon tai toimintaan liittyviä tarpeita, vaatimuksia ja ominaisuuksia. Ohjelmointirajapinnan tarjoaja Organisaation johto - Strategia, tavoitteet , mittarit - Mahdollistajat Kehitys - ja ylläpitotiimi (t) API omistaja: hallinnoi ja priorisoi tarpeita, vaatimuksia ja ominaisuuksia. Suunnittelijat: määrittelee ja suunnittelee API:n, ml API:n tarjoaman tiedon tietomallin. Kehittäjät: toteuttaa API:n. Testaajat: testaa API:n. Ylläpitäjät: käyttöönottaa, ylläpitää ja monitoroi API:a. API / Integraatiotiimi • Kokonaisuuden hallinta. • Yhteistyön ja yhteisöllisyyden edistäminen. • API:en tarjoamiseen ja hyödyntämiseen liittyvien yhteisten käytäntöjen, prosessien, teknologioiden, standardien yms määritys. • Kehitystiimien ohjaus. Muut sidosryhmät Organisaation muut mahdolliset henkilöt tai tiimit, joiden kanssa API-hallintatiimin tulee tehdä yhteistyötä, esimerkiksi: arkkitehtitiimi tai tietoturvatiimi. Ohjelmointirajapinnan hyödyntäjä Organisaation johto* API/Integraatiotiimi Muut sidosryhmät* Kehitys- ja ylläpitotiimi(t) Omistaja, suunnittelijat, kehittäjät, testaajat, ylläpitäjät. * Samat tehtävät kuin ohjelmointirajapinnan tarjoajan vastaavilla rooleilla. Loppukäyttäjille tarkoitetun sovelluksen käyttäminen. 34 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUOTOKSET • Roolien, tehtävien ja vastuiden kuvaukset ja vastuujaot. • Prosessi- ja/tai toimintamallikuvaukset. HYÖDYT • Ohjelmointirajapintoihin liittyvien roolien, tehtävien, vastuiden ja toimintamallien määrittäminen ja kuvaaminen auttavat organisaatiota ja ohjelmointirajapintojen hyödyntäjiä ymmärtämään millaisen API- arvoketjun osa ohjelmointirajapinta on / ohjelmointirajapinnat ovat. • Koko elinkaaren huomioiminen määrityksissä ja kuvauksissa on tärkeää, jotta voidaan varmistaa kehittämiseen tarvittavien tehtävien lisäksi myös tuotannon jatkuvuuteen ja toipumiseen liittyvät tehtävät. • API-arvoketjun ymmärtäminen ja ohjelmointirajapinnan koko elinkaaren huomioiminen edistävät ohjelmointirajapintojen asiakaslähtöisyyttä ja yhteistyötä, uudelleenkäytettävyyttä, tietoturvaa ja tietosuojaa sekä laatua. TUKIMATERIAALI Esimerkkejä ohjelmointirajapintojen ja integraatioiden kehittämiseen sopivista toimintamalleista tai menetelmistä: • ApiOpsCycles, joka tarjoaa menetelmän ja työkaluja ohjelmointirajapintojen kehittämisen eri vaiheisiin49. • DevOps (Development and Operation), jonka periaatteita ovat ketterä kehitys, jatkuva integraatio, jatkuva toimitus ja automaatio50. • DevSecOps (Development, Security and Operation), joka laajentaa DevOpsia tuoden siihen tietoturvan vahvemmin jokaiseen vaiheeseen mukaan51. 49 ApiOpsCycles (APIOps Cycles TM, 2021) 50 Useita eri lähteitä mm. (ite wiki, 2021) ja (DevOps.com, 2021) 51 Useita lähteitä, mm. DevSecOps Fundamentals, s. 17 (Department of Defence, United States of America, 2021) ja DevSecOps Manifesto (DevSecOps, 2021) https://www.apiopscycles.com/ https://devops.com/ https://www.devsecops.org/ 35 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Periaate 2.3 Kuvaa ohjelmointirajapintojen muodostama kokonaisuus Määritä ja ota käyttöön ohjelmointirajapintojen muodostamalle kokonaisuudelle kuvaustapa. Tärkeää on kyetä hallinnoimaan mitä ohjelmointirajapintoja tarjotaan, kenelle ja miksi sekä mitä ohjelmointirajapintoja hyödynnetään, keneltä ja miksi. Tarjottavat ja hyödynnettävät rajapinnat voivat olla organisaation omia sisäisiä rajapintoja (sisäinen API) tai ulkoisia rajapintoja (kumppani API, julkinen API). Ulkoisten rajapintojen tarjoajat tai hyödyntäjät voivat olla kansallisia toimijoita, kuten muu julkinen organisaa- tio tai yksityinen organisaatio tai kansainvälisiä toimijoita, kuten Euroopan unionin muu jäsenvaltio tai kansainvälinen kaupallinen organisaatio. Periaate 3.3 Turvaa, testaa, versioi, dokumentoi ja julkaise ohjelmointirajapinnat määrittää, mitä yksittäisen ohjelmointirajapinnan dokumentaation tulee sisältää. Tämä periaate mää- rittää, mitä meta- ja viitetietoja ohjelmointirajapinnoista tulee kuvata ja hallinnoida osana tiedonhallintamallia, kokonaisarkkitehtuuria tai muuta kokonaiskuvausta. Hyödynnä kokonaisuuden kuvaamisessa organisaatiossa käytössä olevia kokonais- ja ratkaisuarkkitehtuurin kuvauskäytäntöjä. Huomioi kuvauksissa eri arkkitehtuurinä- kökulmat sekä linkitykset tiedonhallintamalliin52: y Toiminta-arkkitehtuurin näkökulmasta ohjelmointirajapinnat osallistuvat jon- kin prosessin tai toiminnallisuuden toteuttamiseen. Linkitys prosessiin voi- daan tehdä esimerkiksi tietovarannon tai tietojärjestelmän kautta. y Tietoarkkitehtuurin näkökulmasta ohjelmointirajapinnat käsittelevät jonkin tai joidenkin tietovarantojen tietoja. y Tietojärjestelmäarkkitehtuurin näkökulmasta ohjelmointirajapinnat liittyvät johonkin tietojärjestelmään. y Teknologia-arkkitehtuurin näkökulmasta ohjelmointirajapinnat hyödyntävät jotain tai joitain teknologiaresursseja. y Integraatioarkkitehtuurin näkökulmasta ohjelmointirajapinnat liittyvät yhteen tai useampaan tietojärjestelmien väliseen liittymään eli tietovirtaan. y Tietoturva-arkkitehtuurin näkökulmasta ohjelmointirajapinnat aiheutta- vat tietoriskejä, jotka pitää tunnistaa ja hallita riskienhallintatoimenpiteiden avulla. y Tiedonhallintamallin näkökulmasta ohjelmointirajapintojen kuvauk- set syventävät tiedonhallintamallin kuvauksia53. Tiedonhallintamallista 52 Tiedonhallintalaki, 5§ (Tiedonhallintalaki 906/2019, 2019), tutustu myös suositukseen tiedonhallintamallista (Valtiovarainministeriö, Tiedonhallintalautakunta, 2020:29) 53 Suositus tiedonhallintamallista (Valtiovarainministeriö, Tiedonhallintalautakunta, 2020:29), tutustu myös suositukseen teknisistä rajapinnoista ja katseluyhteyksistä (Valtiova- rainministeriö, Tiedonhallintalautakunta, 2021:21). 36 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 voidaan johtaa kuvaukset julkisen hallinnon tiedonhallintakarttaan54 ja asiakirjajulkisuuskuvaukseen55. Ohjelmointirajapinnoista kuvattavia asioita ovat: y Nimike: Nimi, tunniste tai muu yksilöivä tieto, jolla ohjelmointirajapinta voi- daan erottaa muista ohjelmointirajapinnoista. y Käyttötarkoitus: Lyhyt sanallinen kuvaus siitä, mihin ohjelmointirajapintaa käytetään. y Omistaja: Henkilö tai tiimi, joka vastaa ohjelmointirajapinnan hallinnoinnista, tarpeista, vaatimuksista ja ominaisuuksista. Esimerkiksi jos ohjelmointiraja- pinta kuuluu osaksi jotain tietojärjestelmää, voi ohjelmointirajapinnan omis- taja olla sama taho kuin tietojärjestelmän omistaja. Jos ohjelmointirajapinta on irrallinen, oma tuotteensa, tulee sillä olla selkeästi määritetty omistaja. y Elinkaari: Elinkaaren tila, joka kuvaa sitä, missä elinkaarensa vaiheessa ohjel- mointirajapinta on. Elinkaaren tilat voidaan johtaa ohjelmointirajapinnan elinkaaren eri vaiheista, joita ovat: määrittely ja suunnittelu, kilpailutus ja han- kinta, toteutus ja kehitys, käyttöönotto, ylläpito, käytöstä poisto. Yksinkertai- simmillaan tilat voivat esimerkiksi olla: kehityksessä / käytössä / poistumassa käytöstä / poistettu käytöstä. y Tietovirta: Linkitys niihin tietojärjestelmien välisiin liittymiin eli tietovirtoihin, joissa kyseistä ohjelmointirajapintaa hyödynnetään. y Tarjoaja: Ohjelmointirajapinnan tarjoaja ja ohjelmointirajapintaan liittyvä tie- tojärjestelmä, jos sellaista on. y Hyödyntäjät: Listaus ohjelmointirajapinnan hyödyntäjistä. Mikäli yksittäi- siä hyödyntäjiä ei tiedetä tai tunnisteta, esimerkiksi jos kyseessä on kaikille avoin julkinen rajapinta, riittää, että kuvataan, kenelle ohjelmointirajapinta on tarkoitettu. y Käsiteltävät tiedot: Mikäli ohjelmointirajapinta käsittelee jotain tietoa, suhde tietoon, tietovarantoon, tietoaineistoon tai tietoryhmään. Huomioi käsiteltä- vissä tiedoissa myös henkilötiedot ja salassa pidettävät tiedot. y Teknologiat: Kuvaus siitä, mitä teknologiaresurssia ohjelmointirajapinta hyödyntää. Kuvaukset tulee pitää ajantasaisina. Hyödynnä tietojen muodostamiseen tai ylläpitoon automatiikkaa mahdollisuuksien mukaan. 54 Julkisen hallinnon tiedonhallintakartta tutkihallintoa.fi -palvelussa (Valtiovarainministe- riö, 2022) 55 Tiedonhallintalain 28§ (Tiedonhallintalaki 906/2019, 2019) 37 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Kuvat 7 ja 8 sisältävät esimerkit ohjelmointirajapintojen kuvauksesta ohjelmointirajapin- nan tarjoajan ja hyödyntäjän näkökulmasta osana organisaation tiedonhallintamallia. Esi- merkissä on huomioitu Tiedonhallintalakiin56 perustuva Tiedonhallintalautakunnan suo- situs57 tiedonhallintamallista. Kuvat ovat kuvitteellisia ja esimerkinomaisia, vaikka perus- tuvatkin Verohallinnon todellisuudessa tarjoamaan tulorekisterirajapintaan58, jonka avulla muut toimijat voivat ilmoittaa automaattisesti palkkatietojaan Verohallinnolle. 56 Tiedonhallintalain 5§ (Tiedonhallintalaki 906/2019, 2019) 57 Suositus tiedonhallintamallista (Valtiovarainministeriö, Tiedonhallintalautakunta, 2020:29) 58 Tulorekisterin tekninen rajapinta (Verohallinto, 2021a) 38 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Kuva 7.  Suositus ohjelmointirajapintojen kuvauksesta osana tiedonhallintamallia ohjelmointirajapinnan tarjoajan näkökulmasta Liittyy hyödyntäjään / hyödyntäjän tietojärjestelmään** Palkkatiedot Ohjelmointirajapinta** Hyödyntäjät: Toimijat X, Y, Z Riskienhallintatoimenpiteet*Riskienhallinta* Riskit Riskiarviointi Omistaja: Maija Meikäläinen Elinkaari: Käytössä * Sisältyy tiedonhallintalaissa ja tiedonhallintalautakunnan suosituksissa määritettyyn tiedonhallintamalliin. ** API - periaatteiden tuoma lisäys tiedonhallintamalliin Ohjelmointirajapinnan tarjoaja: Vero Prosessi*: Tulotietojen keruu Tietovaranto*: Tulorekisteri Sidos prosessiin ja Tietojärjestelmään* Tietojärjestelmä*: Tulorekisteri Tekninen rajapinta Liittymät tietojärjestelmiin* Toimija Z Toimija Y Hyödyntäjä: Toimija X Rajapinta- palvelu Hyödyntäjän tietojärjestelmä* Liittyy tietojärjestelmään ** Liittyy tietojärjestelmien väliseen liittymään eli tietovirtaan** Tulorekisterin reaalikaikainen Web Service-rajapinta Nimike tai muu tunnistetieto: Käyttötarkoitus: Palkkatietojen ilmoittaminen tulorekisteriin Tietovirta: Toimijan X, Y, Z tietojärjestelmät -> Tulorekisteri Tarjoaja: Tulorekisteri-tietojärjestelmä Käsiteltävät tiedot: Palkkatiedot Teknologiat: teknologiaresurssit Käsittelee tietovarannon tietoa / tietoja** Potentiaaliset riskit* Ohjelmointirajapinnat aiheuttavat riskejä** Riskienhallinta- toimenpiteet Ohjelmointirajapinnat tarvitsevat riskienhallintatoimenpiteitä** 39 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Kuva 8.  Suositus ohjelmointirajapintojen kuvauksesta osana tiedonhallintamallia ohjelmointirajapinnan hyödyntäjän näkökulmasta Liittyy tarjoajaan / tarjoajan tietojärjestelmään** Palkkatiedot Tulorekisteri Riskienhallintatoimenpiteet* Riskit Riskiarviointi Ohjelmointirajapinta** Käyttötarkoitus: Teknologiat: N/A Tietovirta: Omistaja: Matti Meikäläinen Elinkaari: Käytössä * Sisältyy tiedonhallintalaissa ja tiedonhallintalautakunnan suosituksissa määritettyyn tiedonhallintamalliin. ** API - periaatteiden tuoma lisäys tiedonhallintamalliin Ohjelmointirajapinnan hyödyntäjä: Toimija X Prosessi*: Palkkatietojen ilmoittaminen Tietovaranto*: HR Sidos prosessiin ja Tietojärjestelmään* Tietojärjestelmä*: Palkkajärjestelmä Rajapinta palvelu Liittymät tietojärjestelmiin* Tarjoaja: Vero Tekninen rajapinta Liittyy tietojärjestelmään** Nimike tai muu tunnistetieto: Tulorekisterin reaalikaikainen Web Service-rajapinta Palkkatietojen ilmoittaminen tulorekisteriin Toimijan X palkkatietojärjestelmä -> Tulorekisteri Tarjoaja: Vero, Tulorekisteri-tietojärjestelmä Hyödyntäjät: Toimijat X, Y, Z Käsiteltävät tiedot: Palkkatiedot Liittyy tietojärjestelmien väliseen liittymään eli tietovirtaan** Käsittelee tietovarannon tietoa / tietoja** Potentiaaliset riskit* Ohjelmointirajapinnat aiheuttavat riskejä** Riskienhallinta* Riskienhallinta- toimenpiteet Ohjelmointirajapinnat tarvitsevat riskienhallintatoimenpiteitä** 40 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUOTOKSET • Ohjelmointirajapintojen kuvaukset esimerkiksi osana tiedonhallintamallia. HYÖDYT • Ohjelmointirajapinnan eri arkkitehtuurinäkökulmien kuvaaminen auttaa organisaatiota ymmärtämään ohjelmointirajapintojen merkityksen omalle toiminnalleen, tietoaineistoilleen, tietojärjestelmilleen, tietovirroilleen ja käytettäville teknologioilleen. • Ohjelmointirajapinnan linkittäminen tietoon, tietoaineistoon tai tietoryhmään on erityisen tärkeää, sillä ohjelmointirajapinnan käsittelemän tiedon luokitus auttaa organisaatiota ymmärtämään ohjelmointirajapinnan aiheuttamat riskit ja tarvittavat tietoturvatoimenpiteet paremmin. • Hallittu ohjelmointirajapintakokonaisuus edistää ohjelmointirajapintojen uudelleenkäytettävyyttä, yhteentoimivuutta sekä tietoturvaa ja tietosuojaa. TUKIMATERIAALI Tutustu myös seuraaviin materiaaleihin, joista voit saada apua kokonaisarkkitehtuurin ja tiedonhallintamallin ymmärtämiseen ja kuvaamiseen: • Tiedonhallintalautakunnan suositus tiedonhallintamallista59. • eOppivan koulutus: Johdanto kokonaisarkkitehtuuriin60. • eOppivan koulutus: Kokonaisarkkitehtuurin mallintaminen61. 59 Tiedonhallintalautakunnan suositus tiedonhallintamallista (Valtiovarainministeriö, Tie- donhallintalautakunta, 2020:29) 60 Johdanto kokonaisarkkitehtuuriin (eOppiva, 2021a) 61 Kokonaisarkkitehtuurin mallintaminen (eOppiva, 2021b) https://julkaisut.valtioneuvosto.fi/handle/10024/162176 https://www.eoppiva.fi/kurssit/johdanto-kokonaisarkkitehtuuriin/#/ https://www.eoppiva.fi/kurssit/kokonaisarkkitehtuurin-mallintaminen/#/ 41 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Periaate 2.4 Tunnista ja hallitse ohjelmointirajapintoihin liittyvät riskit Määritä ja ota käyttöön menetelmä ohjelmointirajapintoihin liittyvien riskien ja uhkien tunnistamiseen sekä riskienhallintatoimenpiteiden toteuttamiseen ja seu- rantaan. Sisällytä riskienhallintatoimenpiteet osaksi ohjelmointirajapintojen toiminnallisia ja ei-toiminnallisia vaatimuksia. Hyödynnä riskienhallintaan Digitaalisen turvallisuuden johtoryhmän VAHTI:n laatimaa ris- kienhallintaohjetta62 ja organisaatiossasi jo olemassa olevia riskienhallinnan prosesseja. Riskienhallinnan prosessi voi edetä esimerkiksi seuraavasti: y Valitse riskienhallinnan kohteena oleva ohjelmointirajapinta tai ohjelmointi- rajapintojen muodostama palvelukokonaisuus. y Tunnista ohjelmointirajapintojen käsittelemät tiedot ja toiminnallisuudet, nii- den luokittelu ja hallinnoijat. y Tunnista ohjelmointirajapintojen kriittisyys toiminnan kannalta ja siihen liit- tyvät tekijät, kuten jatkuvuuteen ja palautumiseen liittyvät reunaehdot. Tun- nista myös ohjelmointirajapinnan toimintaan liittyvät riippuvuudet ja niistä mahdollisesti aiheutuvat kerrannaisvaikutukset. y Tunnista ohjelmointirajapintaan ja sen käsittelemään tietoon tai toiminnalli- suuteen liittyvät uhat ja riskit. Huomioi myös palvelutuotantoon ja palveluta- soihin liittyvät riskit. y Priorisoi tunnistetut riskit ja määrittele niille hallintatoimenpiteet. y Määrittele riskienhallintatoimenpiteiden toteutus- ja seurantavastuut sekä muut mahdolliset jatkotoimenpiteet, kuten ohjelmointirajapintojen jatku- vuus- ja toipumissuunnitelmien teko tai päivitys. Huomioi lakisääteiset vaatimukset tietojen käsittelylle tietoturvatoimenpiteiden suunnittelussa. Turvallisuusluokitellun tiedon käsittelyssä noudatetaan turvallisuusluoki- teltavien asiakirjojen käsittelyohjeita63, luottamukselliset viestintätiedot suojataan sähköi- sen viestinnän palveluista annetun lain64 mukaisesti ja henkilötiedot suojataan ohjelmoin- tirajapinnoissa tietosuoja-asetuksen65 ja -lain66 mukaisesti. 62 VAHTI riskienhallintaohje (Digi- ja väestötietovirasto, 2021a) 63 Suositus turvallisuusluokiteltavien asiakirjojen käsittelystä (Valtiovarainministeriö, Tie- donhallintalautakunta, 2020:19) 64 Laki sähköisen viestinnän palveluista (Laki sähköisen viestinnän palveluista 7.11.2014/917, 2014), tutustu myös Kyberturvallisuuskeskuksen Luottamuksellinen viestintä -sivustoon (Kyberturvallisuuskeskus, 2021b) 65 Yleinen tietosuoja-asetus (Euroopan parlamentin ja neuvoston asetus (EU) 2016/679, 2016/679) 66 Tietosuojalaki (Tietosuojalaki , 5.12.2018/1050) 42 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Huomioi myös, että ohjelmointirajapintoihin liittyvillä riskeillä voi olla heijastusvai- kutuksia muihin tunnistettuihin riskeihin organisaation eri riskienhallinnan tasolla. Kuvassa 9 on esimerkki siitä, miten kolme eri OWASP API Top 10 -riskilistalla67 olevaa ris- kiä voi aiheuttaa tietovuodon, jolloin luonteeltaan tekninen riski voi eskaloitua vahinko- riskiksi, taloudelliseksi riskiksi, toimintariskiksi tai strategiseksi riskiksi. Tämän vuoksi myös ohjelmointirajapintojen riskienhallinnassa tulisi ottaa huomioon tunnistettujen uhkien ja riskien vaikutus organisaation toimintaan. Kuva 9.  Esimerkki ohjelmointirajapintojen aiheuttamasta riskistä 67 OWASP API Top 10 Security Risks (OWASP, 2019) Injektioriski / injection (tekninen riski) Ohjelmointirajapinnan kautta saadaan syötettyä luvatonta ohjelmakoodia, SQL-kyselyitä tai komentoja, jolloin saadaan luvaton pääsy tietoon tai tietojärjestelmiin. Tietovuoto voi sisältää turvallisuusluokiteltua tietoa aiheuttaen vahinkoa organisaatiolle. Tietovuoto voi sisältää arkaluontoista henkilötie- toa aiheuttaen vahinkoa henkilölle. Tietovuoto voi sisältää tietoa, jolla voidaan tehdä fyysistä vahinkoa esimerkiksi teollisuuden ohjauslaitteiden luvattoman käytön kautta. Tietovuoto Tietovuodolla voi olla negatiivinen vaikutus organisaation tai sen toimintayksikköjen toimintaan. Tietovuoto voi esimerkiksi estää kriittisen tietojär- jestelmän toiminnan ja sitä kautta estää organisaation tai sen jonkun toimintayksikön toiminnan. Tietovuoto voi myös vaikuttaa organisaation toimintaan aiheuttamansa mainehaitan kautta. Tietovuoto voi aiheuttaa organisaatiolle vahingon- korvaus-velvollisuuden tai sillä voi olla vaikutus organisaation rahoituk- seen. Tietovuoto voi aiheuttaa myös välillisiä taloudelli- sia riskejä, esimerkiksi palkanmaksu-järjest- elmään liittyvä tietovuoto voi pahimmillaan estää palkanmaksun ja aiheuttaa taloudellisia ongelmia työntekijöille. Tietovuoto voi aiheuttaa myös strategisen tason riskin, mikä voi pahim- millään estää koko organisaation toiminnan tai strategisten tavoitteid- en saavuttamisen. Rikkinäinen objekti tason valtuutus / broken object level authorization (tekninen riski) Ohjelmointirajapinnan URL-osoitetta voidaan manipuloida esimerkiksi hakemaan jokin muu tieto-objekti mitä piti, jolloin saadaan luvaton pääsy tietoon tai tietojärjestelmiin. Rikkinäinen tunnistautuminen / broken authentication (tekninen riski) Ohjelmointirajapinnan tunnistustiedot ovat arvattavissa, kaapattavissa tai tunnistustietojen validointi kyetään ohmittamaan, jolloin saadaan luvaton pääsy tietoon tai tietojärjestelmiin. Taloudellinen riski Vahinkoriski Toimintariski Strateginen riski 43 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUOTOKSET • Riskirekisteri, sisältäen ohjelmointirajapintojen aiheuttamat riskit. • Riskienhallintatoimenpiteet ohjelmointirajapinnoille sisältäen myös jatkuvuuteen ja toipumiseen liittyvät toimenpiteet. HYÖDYT • Ohjelmointirajapintoihin kohdistuvien riskien tunnistamisen ja hallinnan avulla organisaatio voi minimoida ohjelmointirajapintojen toiminnalle tai toiminnan jatkuvuudelle aiheutuvia riskejä ja haittoja. • Riskienhallinta edistää ohjelmointirajapintojen tietoturvaa ja tietosuojaa. TUKIMATERIAALI Tutustu seuraaviin aineistoihin, joista voit saada apua ohjelmointirajapintoihin liittyvien riskien tunnistamiseen ja riskien hallintaan: • Tiedonhallintalautakunnan suosituskokoelma tiettyjen turvallisuussäännösten soveltamisesta68, joka sisältää kuvauksen tietoriskienhallinnasta. • VAHTI riskienhallintaohje69. • Liitteen 1 esimerkki ohjelmointirajapintojen riskienhallinnasta tietoriskianalyysin avulla. • OWASP API Security Top 10 -lista70, joka sisältää ohjelmointirajapintoihin yleisimmin kohdistuvat riskit ja niiden hallintatoimenpiteet. • Kyberturvallisuuskeskuksen Turvallinen tuotekehitys – kohti hyväksyntää opas71, joka sisältää parhaita käytäntöjä haavoittuvuuksien ja muiden yleisimpien ongelmien välttämisestä ohjelmistotuotannossa. • Zero Trust Architecture (englanniksi)72, joka sisältää kuvauksen nollaluottamusmallista. 68 Suosituskokoelma tiettyjen tietoturvallisuussäädösten soveltamisesta (Valtiovarainminis- teriö, Tiedonhallintalautakunta, 2021:65) 69 VAHTI riskienhallintaohje (Digi- ja väestötietovirasto, 2021a) 70 OWASP API Security Top 10 2019 The ten most critical API security risks (OWASP, 2019) 71 Kyberturvallisuuskeskuksen Turvallinen tuotekehitys – kohti hyväksyntää opas (Kybertur- vallisuuskeskus, 2020) 72 Zero Trust Architecture (NIST, 2020) https://julkaisut.valtioneuvosto.fi/handle/10024/163596 https://julkaisut.valtioneuvosto.fi/handle/10024/163596 https://dvv.fi/vahti https://github.com/OWASP/API-Security/raw/master/2019/en/dist/owasp-api-security-top-10.pdf https://www.kyberturvallisuuskeskus.fi/fi/julkaisut/turvallinen-tuotekehitys-kohti-hyvaksyntaa https://www.kyberturvallisuuskeskus.fi/fi/julkaisut/turvallinen-tuotekehitys-kohti-hyvaksyntaa https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-207.pdf 44 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 3.3 Operatiivinen taso Kuva 10.  Operatiivisen tason periaatteet 2 1 4 8 5 6 3.3 Turvaa, testaa, versio, dokumentoi ja julkaise ohjelmointirajapinta. 3.4 Seuraa ohjelmointirajapinnoille asetettuja mittareita ja muita seurantakohteita. TA VO IT TE ET Kerää seurantaa varten tarvittavat tiedot. 9 10 11 Versiointikäytännöt. Rajapintakatalogi. Hyödynnä kerättyä tietoa. 12 7 Toteuta määritetyt tietoturvatoimenpiteet. 3 Tietoturvakontrollit. 3.1 Kehitä ohjelmointirajapinnat avoimilla ja teknologiariippumattomilla standardeilla ja protokollilla. Määritä ja ota käyttöön ohjelmointirajapintojen kehittämisessä tarvittavat standardit, protokollat ja teknologiat. Suosi valinnoissa avoimia, teknologia- riippumattomia standardeja ja protokollia. Ohjeistus käytettävistä standardeista, protokollista ja teknologioista. Valituilla standardeilla ja protokollilla kehitetyt rajapinnat. 3.2 Kuvaa ohjelmointirajapintojen käsittelemät tiedot yhteisten ja yleisten tietomallien mukaisesti. Määritä ja ota käyttöön ohjelmointirajapintojen käsittelemän tiedon kuvaamisessa tarvittavat tietomallit ja metatiedot. Hyödynnä yleisiä tai yhteisiä sanastoja, koodistoja, tietomalleja, tietorakenteita, luokitteluja ja laatukriteerejä. Käytettävät tietomallit ja metatietomallit. Tiedot mallinnettu yhteisten ja yleisten tietomallien mukaisesti. Testaa ohjelmointirajapinta. Julkaise myös hyödyntäjien testausta varten testirajapinta ja testausohjeet. Testitapaukset, -suunnitelmat ja -raportit. Testirajapinta, testausohjeet. Versioi ohjelmointirajapinta. Huomioi sekä taaksepäin yhteensopivat että yhteensopimattomat muutokset ja korjaukset versioinnissa. Dokumentoi ohjelmointirajapinta. Sisällytä dokumentaatioon mm. käyttötarkoitus, palvelutaso, testaus- ja käyttöönottohjeet. Rajapinnan dokumentaatio. Julkaise ohjelmointirajapinta dokumentaatioineen käyttötarkoituksensa mukaisessa julkaisukanavassa ja rajapintakatalogissa. Turvatut, testatut , versioudut ja dokumentoidut rajapinnat julkaisukanavassa. Tunnista seurattavat mittarit ja muut seurantakohteet. Seuraa ja valvo mittareita ja muita seurantakohteita sekä niille asetettuja raja-arvoja. Visualisoi ja raportoi kerättyä tietoa. Seurattavat mittarit ja muut seurantakohteet raja-arvoineen. Lokit, kyselyt. Valvontaratkaisut, automaattiset hälytykset. Raportit ja dashboardit. Automaattiset ja manuaaliset toimenpiteet sekä kehitysideat. 45 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Periaate 3.1 Kehitä ohjelmointirajapinnat avoimilla ja teknologiariippumattomilla standardeilla ja protokollilla Määritä ohjelmointirajapintojen kehittämisessä tarvittavat standardit, protokollat ja teknologiat. Ohjelmointirajapintojen kehittämiseen tarvitaan esimerkiksi: y Tiedonsiirtoprotokolla, joka määrittää millä tavalla tietoa voidaan tuoda tai hakea ohjelmointirajapinnasta. Suositeltavaa on hyödyntää ohjelmointira- japinnoissa ensisijaisesti avoimia, yleisesti käytössä olevia ja teknologia- riippumattomia web-pohjaisia tiedonsiirtoprotokollia. y Tiedostomuoto, joka määrittää missä muodossa ohjelmointirajapinnan käsit- telemä tieto kuvataan. Tiedostomuodon tulee olla koneluettavaa. Tiedosto- muoto voi perustua esimerkiksi johonkin avoimeen tai vaikkapa toimialakoh- taiseen standardiin tai notaatioon. y Tietoturvaan liittyvät protokollat ja menetelmät, joiden avulla voidaan toteuttaa mm. salausta ja pääsynhallintaa. y Toimialakohtaiset standardit, jotka määrittävät jollain tietyllä toimialalla kansallisesti tai kansainvälisesti yhteisesti käytössä olevat tavat. Määritä mitä tiedonsiirtoprotokollia, tiedostomuotoja, tiedon sisältöön tai tietoturvaan liittyviä standardeja, protokollia tai menetelmiä organisaatiossasi käytetään. Suosi valin- noissa avoimia, nykyaikaisia ja yleisesti käytössä olevia teknologiariippumatto- mia standardeja ja protokollia. Huomioi määrityksissä sekä sisäisten (sisäinen API) että ulkoisten (kumppani API, julkinen API) ohjelmointirajapintojen kehittäminen. Huomioi määrityksissä toimialakohtaiset standardit ja ohjeistukset sekä lakisäätei- set tai muut velvoitteet, jotka asettavat vaatimuksia tai rajauksia käytettäville standar- deille tai protokollille. Esimerkiksi laki hallinnon yhteisistä sähköisen asioinnin tukipalve- luista73 asettaa velvoitteen käyttää tietyissä tilanteissa Suomi.fi -palveluväylää74. Velvoit- teen piirissä olevat ohjelmointirajapinnat tulee kehittää Suomi.fi -palveluväylän tukemilla standardeilla tai protokollilla. Huomioi myös, että käytettävien tietoturvaprotokollien tai menetelmien tulee mahdollis- taa riskienhallinnan määrittämien tietoturvatoimenpiteiden toteuttaminen eli ne on valit- tava määritettyjen tietoturvatoimenpiteiden perusteella. Tietoturvatoimenpiteet mää- räytyvät esimerkiksi ohjelmointirajapinnan käsittelemän tiedon turvallisuusluokituksen perusteella. Ota valitut standardit, protokollat ja teknologiat käyttöön ohjelmointirajapintojen kehittämisessä. 73 Laki hallinnon yhteisistä sähköisen asioinnin tukipalveluista 3§, 5§ (Laki hallinnon yhtei- sistä sähköisen asioinnin tukipalveluista, 571/2016) 74 Suomi.fi-palveluväylä (Digi- ja väestötietovirasto, 2021b) 46 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUOTOKSET • Ohjeistus ohjelmointirajapintojen kehittämisessä käytettävistä standardeista, protokollista ja teknologioista. • Valituilla standardeilla ja protokollilla kehitetyt ohjelmointirajapinnat. HYÖDYT • Ohjelmointirajapintojen kehittämistyö tehostuu, ylläpito helpottuu ja erilaisen osaamisen tarve vähenee, kun keskitetään osaamista valittuihin standardeihin, protokolliin ja teknologioihin. • Avointen, yleisesti käytössä olevien standardien, protokollien ja teknologioiden hyödyntäminen edistää ohjelmointirajapintojen uudelleenkäytettävyyttä ja teknistä yhteentoimivuutta. • Osaamisen keskittäminen valittuihin standardeihin, protokolliin ja teknologioihin edistää ohjelmointirajapintojen laatua. 47 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUKIMATERIAALI Esimerkkejä ja lisätietoa tiedonsiirtoprotokollista: • Web-pohjaisissa ohjelmointirajapinnoissa hyödynnetään yleensä http- pohjaista tiedonsiirtoprotokollaa tai arkkitehtuurimallia, kuten SOAP75, REST (Representational State Transfer)76 tai GraphQL77. Web-pohjaisia rajapintoja voidaan hyödyntää sekä sisäisissä että ulkoisissa rajapinnoissa ja niihin saadaan toteutettua laajasti erilaisia tietoturvakontrolleja. Web- pohjaiset rajapinnat mahdollistavat tietojen ja toiminnallisuuksien reaaliaikaisen hyödyntämisen synkronisesti tai asynkronisesti78.Tiedot ja toiminnallisuudet on suositeltavaa tarjota web-pohjaisten rajapintojen kautta, jos mahdollista ja käyttötarkoituksen mukaista. Synkronisuus / asynkronisuus tulee määrittää ohjelmointirajapinnoille asetettujen tarpeiden ja vaatimusten perusteella. • Tiedostopohjaisissa ohjelmointirajapinnoissa hyödynnetään yleensä jotain tiedostopohjaista protokollaa kuten FTP, SFTP tai FTPS. Myös http- pohjaisia protokollia voidaan hyödyntää tiedostojen tarjoamiseen tai vastaanottamiseen. Tiedostopohjaisia ohjelmointirajapintoja voidaan hyödyntää sekä sisäisissä että ulkoisissa rajapinnoissa. Ulkoisissa rajapinnoissa on huolehdittava riittävien tietoturvakontrollien toteuttamisesta. Tiedostopohjaiset rajapinnat ovat hyviä silloin, kun tietoa tai toiminnallisuuksia ei tarvita reaaliaikaisesti tai siirrettävät tiedot ovat tiedostomuotoisia, esimerkiksi kuvia, videoita tai vaikkapa Excel-taulukoita. • Tietokantapohjaisissa ohjelmointirajapinnoissa hyödynnetään yleensä jotain tietokantapohjaista protokollaa, kuten ODBC tai JDBC79, jonka avulla mahdollistetaan toisen tietojärjestelmän, sovelluksen tai ohjelmiston yhteyden avaaminen tietokantaan ja operaatioiden suorittaminen tietokantaa vasten. Tietokantapohjaisia ohjelmointirajapintoja ei suositella käytettävän kuin organisaation sisäisesti. Esimerkiksi tietokantapohjaista rajapintaa voidaan hyödyntää tietojen keräämisessä ETL-integraatiolla80 keskitettyyn tietovarastoon. Mikäli on tarve tarjota jonkin tietovarannon tietoja muille toimijoille, tulee kehittää esimerkiksi web-pohjainen ohjelmointirajapinta tietovarannon ja toisen toimijan väliin. 75 XML Soap (W3Schools, 2021e) 76 RESTFul Web Services (W3Schools, 2021b) 77 A query language for your API (GraphQL Foundation, 2021) 78 Synchronous/asynchronous API (TechTarget, 2017) 79 What is the difference between ODBC and JDBC (Sharma, et al., 2019) 80 ETL (Extract, Transform, Load) (IBM, 2020) https://www.w3schools.com/xml/xml_soap.asp https://www.w3schools.in/restful-web-services/intro/ https://graphql.org/ https://whatis.techtarget.com/definition/synchronous-asynchronous-API 48 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Esimerkkejä ja lisätietoa tiedostomuodoista: • Web-pohjaisissa rajapinnoissa hyödynnetään yleensä XML:ää81 tai JSON:ia82. XML sanomat voidaan kuvata XML skeeman83 avulla ja JSON sanomat JSON Skeeman84 avulla. • Tiedostopohjaisissa rajapinnoissa tiedostomuoto voi oikeastaan olla mitä vain, esimerkiksi kuvatiedosto (.jpg, .gif, .png), videotiedosto (.mp4, .avi) tai taulukko (.xslx, .csv). • Tietokantapohjaisissa rajapinnoissa tiedostomuoto on yleensä tietokannan määrittämä rakenne, joka voi perustua näkymään, tauluun, proceduuriin tai muuhun kantaskriptiin. Esimerkkejä ja lisätietoa tietoturvaan liittyvistä protokollista ja menetelmistä: • Ohjelmointirajapinnoissa tiedon ja tietoliikenteen salaus toteutetaan yleisimmin suojatun HTTPS85-tiedonsiirto- ja TLS86-salausprotokollan avulla. Salauksen lisäksi esimerkiksi kumppaneille tarkoitetuissa ohjelmointirajapinnoissa voidaan hyödyntää myös VPN-teknologioita (Virtual Private Network) tunneloidun yhteyden muodostamiseksi palvelun tarjoajan ja hyödyntäjän välille. Turvallisuusluokiteltavia tietoja käsiteltäessä salauksen tulee noudattaa kyberturvallisuuskeskuksen kryptografisia vahvuusvaatimuksia87. • Ohjelmointirajapinnoissa voidaan hyödyntää esimerkiksi http(s)- protokollan mahdollistamia Basic- tai Bearer-autentikaatioita, API- avaimeen perustuvaa autentikaatiota, OAuth-protokollaa tai siitä johdettuja muunnoksia tai varmenteita. Tunnistusmekanismi on valittava riskiarvioinnin avulla. • Tutustu myös Kyberturvallisuuskeskuksen ohjeistukseen sähköisestä tunnistamisesta88 ja Digi- ja väestötietoviraston tunnistus- ja valtuudet-palveluihin89. 81 XML Tutorial (W3Schools, 2021f ) 82 JSON - Introduction (W3Schools, 2021a) 83 XML Schema Tutorial (W3Schools, 2021d) 84 JSON Schema (JSON Schema, 2021) 85 REST Security Cheat Sheet, HTTPS (OWASP Cheat Sheet Series, 2021a) 86 Transport Layer Protection Cheat Sheet (OWASP Cheat Sheet Series, 2021b) 87 Kyberturvallisuuskeskuksen vahvuusvaatimukset (Kyberturvallisuuskeskus, 2021a) 88 Kyberturvallisuuskeskus, sähköinen tunnistaminen (Kyberturvallisuuskeskus, 2021c) 89 Tunnistus- ja valtuudet palvelut (Digi- ja väestötietovirasto, 2021c), (Digi- ja väestötieto- virasto, 2021d) https://www.w3schools.com/xml/ https://www.w3schools.com/js/js_json_intro.asp https://www.w3schools.com/xml/schema_intro.asp https://json-schema.org/ https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html#https https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Protection_Cheat_Sheet.html https://www.kyberturvallisuuskeskus.fi/sites/default/files/media/regulation/ohje-kryptografiset-vahvuusvaatimukset-kansalliset-suojaustasot.pdf https://www.kyberturvallisuuskeskus.fi/sites/default/files/media/regulation/ohje-kryptografiset-vahvuusvaatimukset-kansalliset-suojaustasot.pdf https://www.kyberturvallisuuskeskus.fi/fi/toimintamme/saantely-ja-valvonta/sahkoinen-tunnistaminen https://www.kyberturvallisuuskeskus.fi/fi/toimintamme/saantely-ja-valvonta/sahkoinen-tunnistaminen https://dvv.fi/tunnistus https://dvv.fi/valtuudet 49 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 Esimerkkejä toimialakohtaisista standardeista ja ohjeistuksista: • Paikkatietoalan standardit ja suositukset90. • Rajapintakartta Sosiaali- ja terveydenhuollon integraatioita ja tietojärjestelmiä varten91. • Suomen Standardisoimisliitto SFS Ry:n standardisoimisryhmien laatimat kansalliset ja kansainväliset standardit92. • Kirjastojen, arkistojen ja museoiden (KAM-sektorin) FINNA- hakuliittymässä, pitkäaikaissäilytyksen Kulttuuriaineisto-PAS -palvelussa sekä muissa yhteisissä järjestelmissä kuten FINTO-ontologiapalvelussa sovellettavat standardit93. • Kansallisten pitkäaikaissäilytyspalveluiden (PAS-palveluiden) säilytys- ja siirtokelpoiset tiedostomuodot94 Periaate 3.2 Kuvaa ohjelmointirajapintojen käsittelemät tiedot yhteisten ja yleisten tietomallien mukaisesti Määritä ja ota käyttöön ohjelmointirajapintojen käsittelemän tiedon kuvaamisessa tarvittavat tietomallit ja metatiedot. Hyödynnä yleisiä tai yhteisiä sanastoja, koo- distoja, tietomalleja, tietorakenteita, luokitteluja ja laatukriteerejä95. Tiedonhallinta- lautakunnan suosituksen mukaan käytettävien sanastojen tulisi perustua laissa säädettyi- hin käsitteisiin eikä niitä tulisi määritellä uudelleen toiseen merkitykseen tai toisen sisältöi- senä. Sanastojen määrittelyyn vaikuttaa se, että perustuslain 2.3 §:n mukaan kaikessa jul- kisessa toiminnassa on tarkoin noudatettava lakia. Laissa säädetyt käsitteet sitovat niiden käyttöä viranomaisten toiminnassa96. 90 Paikkatietoalan standardit ja suositukset (Maanmittauslaitos, 2021a) 91 Rajapintakartta (HL7 Finland, 2021) 92 Standardisointiryhmät (Suomen standardisoimisliitto SFS Ry, 2021a) 93 Digime-standardisalkku (Digime-tietoarkkitehtuuriryhmä, 2021) 94 Säilytys- ja siirtokelpoiset tiedostomuodot (CSC – Tieteen tietotekniikan keskus Oy, 2021) 95 Tiedonhallintalautakunnan suositus teknisistä rajapinnoista ja katseluyhteyksistä, s 11 (Valtiovarainministeriö, Tiedonhallintalautakunta, 2021:21) 96 Lisätietoja Tiedonhallintalautakunnan suosituksesta teknisistä rajapinnoista ja katseluyh- teyksistä (Valtiovarainministeriö, Tiedonhallintalautakunta, 2021:21) https://www.maanmittauslaitos.fi/kartat-ja-paikkatieto/paikkatietojen-yhteentoimivuus/standardit-ja-suositukset http://www.hl7.fi/hl7-rajapintakartta/ http://www.hl7.fi/hl7-rajapintakartta/ https://sfs.fi/osallistu-ja-vaikuta/standardisointiryhmat/?fwp_aihealueet=tieto-ja-viestintatekniikka https://sfs.fi/osallistu-ja-vaikuta/standardisointiryhmat/?fwp_aihealueet=tieto-ja-viestintatekniikka https://www.doria.fi/handle/10024/180685 https://www.doria.fi/handle/10024/180685 https://www.doria.fi/handle/10024/180685 https://www.doria.fi/handle/10024/180685 https://www.digitalpreservation.fi/specifications/fileformats https://www.digitalpreservation.fi/specifications/fileformats 50 VALTIOVARAINMINISTERIÖN JULKAISUJA 2022:12 TUOTOKSET • Ohjeistus ohjelmointirajapintojen tietojen kuvaamisessa käytettävistä yhteisistä ja yleisistä tietomalleista ja metatietomalleista. • Ohjelmointirajapintojen käsittelemät tiedot on mallinnettu yhteisten ja yleisten tietomallien mukaisesti. HYÖDYT • Ohjelmointirajapintojen käsittelemien tietojen mallinnus tehostuu ja helpottuu, kun voidaan hyödyntää jo olemassa olevia tietomalleja, metatietomalleja, koodistoja ja sanastoja eikä tarvitse keksiä näitä joka kerta uudelleen. • Yhteiset tietomallit, metatietomallit, koodistot ja sanastot edistävät ohjelmointirajapintojen uudelleenkäytettävyyttä, semanttista yhteentoimivuutta ja laatua. TUKIMATERIAALI Tukimateriaaleja, joista voit saada apua yhteisten ja yleisten tietomallien, metatietomallien, sanastojen ja koodistojen tunnistamisessa: • Yhteentoimivuusalusta ja yhteentoimivuusmenetelmä97, joka sisältää työkalut yhteentoimivien tietosisältöjen määrittelyyn. • Tilastokeskuksen tiedon laatukriteerit ja mittarit98, joka sisältää ohjeita tietoaineistojen laadun kuvaamiseen ja arvioimiseen. • Kuntaliiton julkaisema Yhteento