Koodistoeditorin toteutuksen lähtökohtia: KaPA-koodistopalvelu ja REST-rajapinnat

Transkriptio

1 Koodistoeditorin toteutuksen lähtökohtia: KaPA-koodistopalvelu ja REST-rajapinnat Yhteinen tiedon hallinta (YTI) -hanke Antti Tohmo Kansallinen koodistoeditori -työpaja Väestörekisterikeskus, Lintulahdenkuja 4, Helsinki

2 KaPA-koodistopalvelu

3 KaPA-koodistopalvelu Tarjoaa modernit ja ajantasaiset koodistorajapinnat Suomi.fipalveluiden käyttöön. Osa kansallisen palveluarkkitehtuurin toteutusta, KaPA. Aggregoi muiden tuottamaa avointa koodistodataa. Selkeät rajapinnat, yhtenevä formaatti. Muodostaa linkityksiä eri koodistoissa olevien koodien välille.

4 Miksi tehtiin KaPA-koodistopalvelu? Eri palvelut toteuttaneet omat koodistopalvelunsa. Tiedot eivät välttämättä yhtenäisessä muodossa. Ratkaisut eivät ole yleiskäyttöisiä, rajapinnat harvoin julkisia. Hankala ylläpidettävyys ongelmana kaikilla. Tieto ei välttämättä ajantasaista, yleinen ongelma jopa lähteissä. Kertyy paljon turhaa duplikaattityötä, etenkin uusissa projekteissa. Ongelma on kuitenkin ratkaistavissa yleisellä tasolla, sillä data avointa. KaPA-koodistopalvelua toteuttaessa kansallisen koodistopalvelun tarpeellisuus tuli selväksi.

5 KaPA-koodistot

6 KaPA-koodistot Palvelu ei itsessään tuota tai hallinnoi dataa, lähteinä eri organisaatiot. Tarjoaa vain voimassaolevat koodistot, ei historioitua dataa. Lähteissä saatavilla usein vain tämänhetkinen voimassaoleva data. Lukuisia tiedonlähteitä eri koodisto-aineistoille. Posti, Avoindata, Kuntaliitto, YritysSuomi, Tilastokeskus, YTJ, muut koodistopalvelut, jne. Integraatioita eri jakelumenetelmiin ja formaatteihin. Excel, CSV, JSON, tekstitiedostot, verkkosivustot, rajapinnat. Kukin tapaus vaatii spesifin ja yksilöidyn käsittelyn. Koodisto-tiedoille ei ole siis tällä hetkellä olemassa kansallista yhtenäistä rajapintaa tai formaattia. YTI ratkaisee tämän.

7 Toteutetuttuja koodistorajapintoja /api/v1/postalcodes/ - Postikoodit lähde: Posti /api/v1/postmanagementdistricts/ - Postin hallintoalueet lähde: Posti /api/v1/municipalities/ - Kunnat lähde: AvoinData /api/v1/regions/ - Maakunnat lähde: AvoinData /api/v1/healthcaredistricts/ - Sairaanhoitopiirit lähde: Kuntaliitto / Tilastokeskus /api/v1/electoraldistricts/ - Vaalipiirit lähde: AvoinData /api/v1/streetaddresses/ - Katuosoitteet lähde: Posti /api/v1/businesservicesubregions/ -Yrityspalvelujen seutualueet lähde: YritysSuomi /api/v1/businessids/ -Y-tunnukset lähde: YTJ / PRH

8 KaPA-koodistopalvelun arkkitehtuuri

9 Mikropalveluarkkitehtuuri Palvelu hajautettu pienemmiksi kokonaisuuksiksi, mikropalveluiksi. Vastakohta monoliitti-mallille, jossa yksi sovellus toteuttaa kaiken logiikan, eikä välttämättä tarjoa rajapintoja lainkaan. Tavoitteena ollut kestävä malli, joka tarjoaa skaalautuvan ja ylläpidettävän ratkaisun. Mikropalvelut keskustelevat toistensa kanssa HTTP-rajapintojen kautta. Kokonaisuus muodostuu mikropalveluiden vuorovaikutuksesta.

10 Arkkitehtuuri-kuvaus

11 Teknologia-stack Java Ohjelmointikieli, jolla KaPA-koodistopalvelu on toteutettu Spring Boot Framework nopeaan Web-sovelluskehitykseen Jersey Framework RESTful-palveluiden rakentamiseen Jackson JSON-serialisointikirjasto Maven Sovellusten build-hallinnointi PostgreSQL Relaatiotietokanta ElasticSearch Hakutietokanta Docker Virtualisointimekanismi, jolla voidaan ajaa kontitettuja -palveluita Swagger Työkalu ja spesifikaatio RESTful-rajapintojen dokumentaatioon

12 REST-rajapinnat

13 REST-rajapinnat 1/2 REST Best Practices Resurssien ja parametrien nimeämiskäytännöt. HTTP-protokollan noudattaminen. Resursseja käytetään HTTP verbein: GET, POST, PUT, PATCH, DELETE. Selkeys ja helppokäyttöisyys Hyödynnetään standardeja. Rajapinnat sekä paluuarvot ihmisen luettavassa muodossa. JSON JavaScript Object Notation Yksikäsitteisyys Resursseihin viitataan URI-osoitteella. Suositaan loogisia ja ymmärrettäviä nimiä hankalaselkoisten generoitujen nimien sijaan.

14 REST-rajapinnat 2/2 Listarajapintojen geneeriset toiminnot Hakutoiminnot nimen, koodin tai muun merkitsevän arvon perusteella. Sivutus pagesize ja from parametreillä. Metatiedot koodeille ja koodistoille KaPA-palvelut ovat määritelleet tarpeet KaPA-koodistopalvelussa. Ei kattavaa metatieto-luokittelua, tarjolla vain lähteistä poimitut avainarvot. Rajapintojen hierarkian pelkistäminen Linkitetyt resurssit kuvataan URI-viittein, tiedot laajennettavissa expand - parametrilla.

15 Rajapintojen dokumentaatio Swagger-spesifikaatio, Rajapintojen listaus ja kuvaus. API-arvojoukkojen kuvaukset. Dokumentaatio toteutetaan Java-koodissa, rajapintojen ja niihin liittyvien luokkien toteutuksen yhteydessä. Käytetty mekanismi: Java-annotaatiot. Helposti ylläpidettävä, pysyy ajantasalla rajapinta-kehityksen rinnalla. Jakelu automatisoitu. Swagger UI visualisointi. Saatavilla kustakin ajavasta ympäristöstä kohdistetusti. Tarjoaa rajapintojen selauksen, helpon testikäytön ja kokeilun, Try it out!

16 Swagger-demo

17 { "swagger" : "2.0", "info" : { "description" : "Code List Service - Public API Service - Spring Boot microservice.", "version" : "v1", "title" : "Code List Service - Public API Service", "termsofservice" : " "contact" : { "name" : "Code List Service by the Population Register Center of Finland", "url" : " " " : kapa@vrk.fi }, "license" : { "name" : "MIT", "url" : } }, "host" : "localhost", "basepath" : "/cls-api/api", "tags" : [ { "name" : "api", "description" : "Code List Service - Public API Service }, { "name" : "businessids", "description" : "Operations about businessids. }, { "name" : "businessservicesubregions", "description" : "Operations about businessservicesubregions. }, { "name" : "electoraldistricts", "description" : "Operations about electoraldistricts. }, { "name" : "healthcaredistricts", "description" : "Operations about healthcaredistricts. }, { "name" : "hello", "description" : "Example public hello operation. }... } swagger.json

18 Swagger UI

19 Rajapinta esimerkkejä

20 Rajapinta-esimerkkejä alanraitti/42/

21 Rajapinnat: hakutoiminnot Lista-rajapinnat tukevat spesifejä hakutoimintoja. Haut toteutettu prefix-tyyppisesti. Esimerkki: Palauttaa kaikki alkuiset postikoodit.

22 Rajapinnat: sivutus Lista-rajapinnat tukevat sivutusta. pagesize -parametri määrää sivun koon. from -parametri määrää sivutuksen aloitusindeksin. Esimerkki:

23 Rajapintojen pelkistys Hierarkiset arvot palautetaan pelkistetyssä URI-muodossa. ty,postmanagementdistrict expand -parametrilla saadaan avattua spesifit hierarkiset arvot paluuarvoihin. Postinumeroa vastaava kunta linkitettynä resurssina.

24 YTI-toteutus

25 KaPA YTI KaPA-koodistopalvelun koodipohja forkattu soveltuvin osinyti-hankkeen Koodistoeditorin lähtökohdaksi. Julkaistu avoimena: 7 repositorion kokonaisuus (mikropalvelut, konfiguraatiot, middleware). KaPA-koodistopalvelun puutteet YTI-näkökulmasta Tarvitaan yhtenäinen ja laajennettava tietomalli nykyisen arkkitehtuurin päälle. Tulee toteuttaa käyttöliittymät ja rajapinnat myös koodistodatan ja käyttäjäryhmien hallinnointiin. Datan historiointi ja versiointi. Hyvien rajapintojen kautta mahdollistetaan datan monipuolinen hallinnointi ja jakelu, sekä siihen kytkeytyvien sovellusten mutkaton kehitys.

26 Kiitos! yhteentoimivuus.slack.com