Rajapinnan lisääminen

 

Lisää dataa rajapintana tuottajalle 

Lisää ainoastaan ohjelmointirajapintoja rajapintana avoindata.fi:hin. Jos haluat lisätä rajapinnan kautta saatavia aineistoja, lisää ne tietoaineistoina. 

Mikä on rajapinta?

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. 


Voit lisätä rajapintoja, kun olet rekisteröitynyt palveluun ja kirjautunut sisään. Sinulla tulee myös olla Ylläpitäjä- tai Muokkaaja-roolin oikeudet siinä organisaatiossa, jolle haluat lisätä rajapinnan. Lue lisää jäsenyydestä Organisaation jäsenet -osiosta.

Jos organisaatiotasi ei ole vielä lisätty palveluun, lue, miten lisäät uuden tuottajan

Näin lisäät ja kuvailet rajapinnan

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. Jos olet esimerkiksi lisäämässä ostolaskuja, tutustu ensin muiden organisaatioiden lisäämiin ostolaskuihin.

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 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 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.
    • Yksityiset rajapinnat näkyvät 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.

Lisää linkki rajapintaan tai sen dokumentaatioon

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