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. 

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

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

Aloita lisääminen täydentämällä rajapinnan kuvailutiedot eli metatiedot ja lisää sen jälkeen linkki rajapintaan tai sen dokumentaatioon. Pakolliset kentät on 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 rajapinnalle nimi

Rajapinnan nimen tulee kertoa seuraavat asiat:

• Organisaatio, 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 rajapinnan URL-osoitteen automaattisesti sen nimen perusteella. Jos osoite on sama kuin jollain muulla aineistolla, saat virheilmoituksen ja sinun täytyy muokata osoitetta. 

2. Kirjoita rajapinnalle kuvaus

Kuvauksessa on hyvä kertoa seuraavat asiat:

• 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

Näkyvyydeksi tulee valita 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

Kerro lisenssin valinnan yhteydessä, miten datan hyödyntäjien tulee viitata dataasi. 

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. Jos käytät CC-BY-4.0-lisenssiä määrittele rajapinnan kuvaukseen, miten haluat, että organisaatiosi nimetään, kun joku hyödyntää rajapinnan tarjoamaasi dataa.
• Creative Commons CC0 1.0 -lisenssi ei määrittele datan uudelleenkäytölle minkäänlaisia rajoitteita. Tätä lisenssiä käytetään usein metatietoihin.

Voit lukea lisenssin valinnasta lisää tiedon jakamisen toimintamallista.

6. Määrittele rajapinnan käyttöehdot

Kerro käyttöehdoissa seuraavat tiedot:

• 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

Lisää rajapinnan ylläpitäjäksi joko organisaatio tai esimerkiksi organisaation yksikkö tai osasto, joka on vastuussa julkaistusta datasta.

Käytä organisaation yleistä sähköpostia esimerkiksi kirjaamo@organisaatio.fi tai avoindata@organisaatio.fi.

8. Siirry lisäämään linkki rajapintaan tai sen dokumentaatioon valitsemalla Seuraava.

Lomakkeella näkyvistä tyhjistä muokattavista kentistä ei tarvitse välittää. Voit käyttää niitä, jos haluat lisätä tietoaineistolle tietoa, jolle ei ole lomakkeella omaa kenttää. Niihin kirjoitettu tieto ei näy rajapinnan sivulla.

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

Näin lisäät rajapinnalle resurssin

1. Nimeä resurssi

Käytä kuvailevaa nimeä, esimerkiksi Rajapinnan OpenAPI-dokumentaatio tai Rajapinnan endpoint-osoite.

Jos et nimeä resurssia, 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

Teknisessä kuvauksessa voit kertoa esimerkiksi rajapinnan palauttaman datan tiedostomuodosta ja rajapinnan kyselymuodoista. 

Lisää tekniseen kuvaukseen myös linkki teknisiin lisätietoihin. 

4. Valitse, vaatiiko rajapinnan käyttö rekisteröitymisen

Jos rajapinnan hyödyntäjien täytyy rekisteröityä tai tunnistautua ennen kuin he voivat käyttää rajapintaa, valitse Kyllä. 

Lisäksi kerro rekisteröitymisprosessi rajapinnan kuvauksessa.

​5. Valitse lopuksi Lisää rajapinta.

Jos haluat lisätä samalla kerralla rajapinnalle useamman resurssin, 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, ajoradat 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 sitten valitse Muokkaa rajapintaa.

2. Valitse välilehti Liitä tietoaineistoja. 

3. Etsi tietoaineistoja kirjoittamalla niiden nimi hakukenttään. 

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ä.

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

​​​​​​​​