Ohjelmointirajapinnat eli APIt (Application Programming Interface) ovat dokumentoituja rajapintoja, joiden avulla ohjelmistot, sovellukset tai järjestelmät voivat vaihtaa keskenään tietoa tai toimintoja. Ohjelmointirajapinta tarjoaa tietoa tai toimintoa koneluettavassa, dokumentoidussa muodossa siten, että jokin toinen ohjelmisto, sovellus tai järjestelmä voi sitä ohjelmallisesti hyödyntää. Esimerkiksi joukkoliikenteen rajapinta kertoo reittiopas-sovellukselle, milloin bussisi saapuu pysäkille. 

Lisää rajapintoja Rajapinnat-sivulta Lisää rajapinta -painikkeesta.

Tarkista ensin, onko joku muu organisaatio julkaissut samankaltaista dataa kuin olet itse julkaisemassa. Jos on, ota mallia heidän julkaisustaan ja käytä esimerkiksi samanlaisia avainsanoja ja kategorioita. 

Näin lisäät rajapinnan

Aloita lisääminen täydentämällä rajapinnan kuvailutiedot eli metatiedot ja lisää sen jälkeen linkki rajapintaan tai sen dokumentaatioon. Pakolliset kentät ovat merkitty lomakkeeseen tähdellä *.

Kuvaile rajapinta kattavasti, sillä se parantaa sen löydettävyyttä ja helpottaa datan hyödyntämistä.

Lisää metatiedot myös ruotsiksi ja englanniksi, jotta muutkin kuin suomenkieliset datan hyödyntäjät voivat käyttää dataa. Datat kopioituvat myös Euroopan yhteiseen data.europa.eu-palveluun, josta kansainväliset hyödyntäjät löytävät datan.

1. Anna rajapinnallesi nimi, joka kertoo:
   • Organisaation, joka tarjoaa rajapinnan.
   • Minkälaista dataa rajapinta tarjoaa tai mikä on rajapinnan käyttötarkoitus.
   • Mikä on rajapinnan formaatti.
   • Esimerkiksi Turun kaupungin paikkatietorajapinta (WMS)

   • Palvelu luo URL-osoitteen automaattisesti sen nimen perusteella. Jos osoite on sama kuin jollain muulla aineistolla, saat virheilmoituksen ja sinun täytyy muokata osoitetta. 

2. Kirjoita kuvaukseen:
   • Millaista dataa rajapinta tarjoaa?
     • Esimerkiksi, millaisia paikkatietoaineistoja sen kautta on saatavilla.
   • Missä rajapinnan tarjoamaa dataa voi hyödyntää?
     • Jos jokin organisaatio ottaisi rajapinnan käyttöönsä, mitä organisaatio voisi rajapinnan avulla tehdä. 
   • Mitä rajapinnan käyttöönottovan organisaation pitää tehdä, jotta se voi alkaa käyttää rajapintaa?
   • Mistä organisaation edustaja voi lukea lisää rajapinnan toiminnasta, sen käytöstä ja sen tarjoamasta datasta?
3. ​​Lisää rajapintaa kuvaavia avainsanoja ja sille sopivat kategoriat. 
   • 
   • Avainsanat-kenttä ehdottaa jo aiemmin käytettyjä avainsanoja. Suosittelemme käyttämään paljon käytössä olevia avainsanoja. 
4. Valitse rajapinnan näkyvyydeksi julkinen, sillä kaikki palvelussa oleva data on julkista avointa dataa, eikä palveluun saa lisätä yksityiseksi tarkoitettuja aineistoja. Jos haluat pitää rajapinnan väliaikaisesti luonnostilassa esimerkiksi testausta tai tietojen täydennystä varten, valitse tilaksi yksityinen.
   • 
   • Yksityinen rajapinta näkyy kaikille sen julkaisseen organisaation jäsenille.
5. Valitse rajapinnan tarjoamalle tiedolle sen käyttöehdot määrittelevä lisenssi. Avoimella datalla täytyy aina olla avoin lisenssi. Valitse joko CC BY 4.0 tai CC0 1.0 -lisenssi:
   • 
   • Creative Commons Nimeä 4.0 (CC BY 4.0) -lisenssiä käytettäessä datan hyödyntäjän pitää nimetä datan alkuperä, tarjota linkki lisenssiin ja kertoa, jos dataan on tehty muutoksia. 
   • Creative Commons CC0 1.0 -lisenssi ei määrittele tietoaineiston uudelleenkäytölle minkäänlaisia rajoitteita. Tätä lisenssiä käytetään usein metatietoihin.
   • Jos käytät CC-BY-4.0-lisenssiä määrittele rajapinnan kuvaukseen, miten haluat, että organisaatiosi nimetään, kun joku hyödyntää rajapinnan tarjoamaa dataa.
6. Määrittele rajapinnan käyttöehdot.
   • Kerro, vaatiiko rajapinnan käyttö API-avaimen ja jos vaatii, mistä sen voi saada. Jos rajapinta vaatii rekisteröitymisen, kerro rekisteröitymisprosessista tässä.
   • Anna linkki rajapinnan käyttöehtoihin ja mahdolliseen palvelutasolupaukseen (SLA).
   • Kerro myös mahdollisista muista rajoitteista rajapinnan käytössä. 
7. Lisää rajapintaa ylläpitävän organisaation tiedot. Käytä organisaation yleistä sähköpostia esimerkiksi kirjaamo@organisaatio.fi tai avoindata@organisaatio.fi.
   • Lisää rajapinnan ylläpitäjäksi joko organisaatio tai esimerkiksi organisaation yksikkö tai osasto, joka on vastuussa julkaistusta datasta.
   • 
8. Siirry lisäämään linkki rajapintaan tai sen dokumentaatioon valitsemalla Seuraava.
   • Lomakkeella näkyvistä tyhjistä muokattavista kentistä ei tarvitse välittää. Niitä voi käyttää, jos haluat lisätä tietoaineistolle tietoa, jolle ei ole lomakkeella omaa kenttää. Niihin kirjoitettu tieto ei näy tietoaineiston sivulla.

Seuraavaksi rajapinnalle pitää lisätä resurssi eli rajapinnan endpoint-osoite tai linkki rajapinnan dokumentaatioon.

Näin lisäät rajapinnalle resurssin

1. Nimeä resurssi kuvailevasti. Esimerkiksi Rajapinnan OpenAPI-dokumentaatio tai Rajapinnan endpoint-osoite. Jos et nimeä data-aineistoa, sen nimeksi tulee URL-osoite tai liittämäsi tiedoston tiedostonimi.

2. ​Lisää linkki rajapintaan tai sen dokumentaatioon. Voit myös lisätä pdf-tiedoston, jos esimerkiksi rajapinnan ohjeet ovat pdf-muodossa.

   
3. Kirjoita tekninen kuvaus rajapinnalle, jossa voit kertoa esimerkiksi rajapinnan tiedon tiedostomuodosta ja rajapinnan kyselymuodoista.
   •  
   • Lisää tekniseen kuvaukseen myös linkki teknisiin lisätietoihin. 
4. Valitse, täytyykö rajapinnan hyödyntäjien rekisteröityä tai tunnistautua ennen kuin he voivat käyttää rajapintaa.
   • 
   • Jos valitset Kyllä, kerro rekisteröitymisprosessi rajapinnan kuvauksessa.
5. ​Valitse lopuksi Lisää rajapinta.
   • 
   • Jos haluat lisätä samalla kerralla rajapinnalle useamman linkin, valitse Tallenna ja lisää toinen.​​

Jos rajapinnan tarjoamista tiedoista on koostettu tietoaineistoja, voit liittää ne rajapintaan. Tietoaineistojen pitää ensin olla lisätty avoindata.fi:hin. 

Esimerkiksi paikkatietorajapinnoista voi olla tarve koostaa erilaisia karttatasoja omiksi aineistoikseen, kuten sillat, ajorajat tai vesistöt. Nämä aineistot voi liittää itse paikkatietorajapintaan, jotta ne löytyvät avoindata.fi:stä helpommin. 

 Näin liität tietoaineistot rajapintaan

 

Varmista, että olet lisännyt tietoaineistot sekä rajapinnan ensin avoindata.fi:hin.

1. Valitse rajapinta, johon haluat liittää tietoaineistoja ja valitse Muokkaa rajapintaa.
   • 
2. Valitse välilehti Liitä tietoaineistoja. 
   • 
3. Etsi tietoaineistoja niiden nimellä ja paina enter suorittaaksesi haun. 
4. Valitse liitettävät tietoaineistot ja tallenna valinnat valitsemalla Liitä rajapintaan.
   • 
5. Tietoaineistot on nyt liitetty rajapintaan. Näet ne rajapinnan sivulla.
   • 

Voit poistaa liittämäsi tietoaineistot samalta Liitä tietoaineistoja -välilehdeltä. 

1. Valitse ensin tietoaineisto, jonka haluat poistaa rajapinnasta ja sitten Poista rajapinnasta.
   • ​​​​​​​​