Alijärjestelmän ja palveluiden kuvaaminen Liityntäkatalogiin
Tämä ohje neuvoo, miten palveluntarjoajien tulee kuvata alijärjestelmänsä ja palvelunsa LiityntäkatalogiinAvautuu uuteen ikkunaan..
Palveluita kuvailevat tiedot kertovat Liityntäkatalogia selaavalle, minkälaisia palveluita Suomi.fi-palveluväylän kautta on tarjolla. Palveluista kerrotaan yleisesti alijärjestelmän kuvauksessa, mutta tarkemmat kuvaukset löytyvät palveluiden (rajapintojen) kohdalta.
Sinun tulee olla kirjautuneena Liityntäkatalogiin ja sinulla tulee olla oikeudet muokata organisaatiosi tietoja Liityntäkatalogissa.
Saat oikeudet muokata tietoja organisaatiosi ylläpitäjältä. Ohjeet Liityntäkatalogin käyttäjähallintaan löydät tukiartikkelista. Jos organisaatiossasi ei ole henkilöä, jolla olisi oikeudet muokata organisaatiosi tietoja, pyydä oikeuksia ja tunnuksia Palveluväylän ylläpidolta: palveluvayla@palveluvayla.fi.
Muuttaaksesi alijärjestelmäsi tietoja, mene sen tietoihin Liityntäkatalogissa ja valitse Hallinnoi.
Alijärjestelmän nimi siirtyy automaattisesti Palveluväylästä, mutta voit muuttaa nimeä Liityntäkatalogissa. Suosittelemme, että vaihdat alijärjestelmän nimen sellaiseksi, että se kuvaa alijärjestelmän palveluita yleistajuisesti.
Alijärjestelmän kuvaus kertoo, mitä palveluja ja tietoja alijärjestelmä tarjoaa ja miten palveluita voi ottaa käyttöön. Alijärjestelmän kuvaus on sen palveluja eli rajapintoja ja sisältötietoja markkinoiva palvelulupaus.
Jos alijärjestelmä vain hyödyntää muita palveluita, käytä kuvauksessa seuraavaa virkettä: "Alijärjestelmä ei tarjoa palveluita, vaan pelkästään hyödyntää Suomi.fi-palveluväylän kautta saatavaa tietoa."
Suosittelemme, että alijärjestelmä on palvelukohtainen. Jos samalla alijärjestelmällä kuitenkin on useampi palvelu, voit kuvata yksittäistä palvelua tarkemmin palvelun omassa kuvauksessa.
Kerro alijärjestelmästä seuraavat tiedot:
Alijärjestelmän nimi
Alijärjestelmän kuvaus
- Alijärjestelmän yleiskuvaus: Millaisia palveluita alijärjestelmä tarjoaa ja millä kielillä? Mitä hyötyjä palvelun käyttöön liittyy? Kerro kuvauksessa, miten muut organisaatiot voivat hyötyä palveluista. Näin toiset organisaatiot saavat yleiskuvan palvelusta ja voivat arvioida, kannattaisiko heidän organisaationsa ottaa se käyttöön. Miten palveluista saa lisätietoja?
- Palveluiden käytön edellytykset ja rajoitukset: Mitkä organisaatiot voivat ottaa palveluita käyttöönsä? Vaatiiko palveluiden käyttöönotto erillisiä lupahakemuksia? Kuvaile lupaprosessi.
- Palveluiden käyttöönotto: Miten palveluita saa käyttöönsä? Kuvaile käyttöönottoprosessi. Mistä voi saada lisätietoja palveluiden käyttöönotosta?
Asiasanat
- Anna alijärjestelmälle sen tarjoamia palveluita kuvaavia tai siihen oleellisesti liittyviä asiasanoja. Esimerkiksi vtjrajapinta-alijärjestelmälle on annettu asiasanoiksi ”väestötietojärjestelmä”, ”henkilötunnus”, ”henkilötiedot”, jne.
- Liityntäkatalogin haku kohdistuu nimen ja tekstikenttien lisäksi asiasanoihin. Hyvin asiasanoitettu alijärjestelmä ja sen palvelut löytyvät Liityntäkatalogista siis helpommin. Kun annat alijärjestelmälle asiasanoja, kannattaa miettiä, millä hakusanoilla itse etsisit kyseisiä palveluja.
- Voit etsiä sopivia ja yleisesti käytettyjä asiasanoja yleisistä ontologioista tai muista oman alan asiasanastoista. Esimerkiksi Suomalainen asiasanasto- ja ontologiapalvelu Finto ylläpitää Yleistä suomalaista ontologiaa YSO:a.
Ylläpitäjän yhteystiedot
- Kerro alijärjestelmän ylläpitäjän yhteystiedot, jotta kiinnostuneet organisaatiot voivat kysyä lisätietoja sen sisältämistä palveluista.
- Anna organisaation toimialakohtainen sähköpostipostiosoite henkilökohtaisen osoitteen sijasta, jos se on mahdollista. Näin palveluita koskevat tiedustelut eivät jää käsittelemättä esimerkiksi henkilökohtaisten poissaolojen vuoksi.
Alijärjestelmän näkyvyys
- Voit julkaista alijärjestelmän Liityntäkatalogissa kaikkien Liityntäkatalogia selailevien nähtäväksi siirtämällä sen Julkinen-tilaan. Yksityinen-tilassa vain alijärjestelmää hallinnoivan organisaation jäsenet näkevät sen Liityntäkatalogissa.
- Yksityinen-tilaa voi käyttää esimerkiksi, jos alijärjestelmän kuvaus ei ole vielä valmis, eikä sitä haluta siksi näyttää julkisesti Liityntäkatalogissa.
Voimassaoloaika
- Ilmoita Voimassaolo alkaa -kohdassa, mistä alkaen alijärjestelmän palvelut tai palvelu on käytössä. Jos palvelu on voimassa toistaiseksi, ei Voimassaolo päättyy -kohdassa tarvitse ilmoittaa mitään. Jos kuitenkin tiedossa on päivämäärä, jolloin palvelu muuttuu tai poistuu Palveluväylästä, ilmoita se Voimassaolo päättyy -kohdassa.
Huomioi kuvausta tehdessä myös:
- Älä kirjoita kuvausta liian teknisellä kielellä, vaan pyri yleistajuiseen ilmaisuun. Kirjoita kuvaus ytimekkäästi, mutta muista kertoa kaikki oleellinen. Katso esimerkiksi Digi- ja väestötietoviraston kuvaus VTJ-rajapinta-alijärjestelmästä ja Valtuudet-palvelusta.
- Käytä muotoiluja. Muotoilujen käyttäminen parantaa tekstin ymmärrettävyyttä. Kuvausteksti kannattaa jakaa alaotsikoinnin avulla kolmeen yllä esitettyyn eri osioon: Alijärjestelmän yleiskuvaus, Palveluiden käytön edellytykset ja rajoitukset sekä Palveluiden käyttöönotto. Voit myös korostaa tekstin tärkeimpiä kohtia käyttämällä lihavointia.
- Kirjoita kuvaus myös ruotsiksi ja englanniksi. Kuvauksen kieliversiot täydennetään omiin kenttiinsä ja ne näkyvät, jos käyttäjä käyttää Liityntäkatalogia eri kielellä. Muista päivittää myös kuvauksen kieliversiot, kun päivität kuvausta.
Muuttaaksesi yksittäisen palvelun tietoja, mene Liityntäkatalogissa sen alijärjestelmän tietoihin, jonka kautta palvelu tuodaan Palveluväylään. Valitse sivun Palvelut-osiosta se palvelu, jonka tietoja haluat muuttaa ja valitse sitten aukeavalta sivulta Hallinnoi.
 kuvaukset Liityntäkatalogissa-beba79e992d85fd8d1b4403843db7610.webp)
Muokkaa tarvittaessa yksittäisen palvelun tietoja. Voit muokata seuraavia tietoja:
- Palvelun kuvaus: Lisää palvelulle lyhyt yleisluontoinen kuvaus, jotta muut, jotka haluavat hyödyntää palveluasi (rajapintaasi), ymmärtävät sen toimintaa paremmin.
- Palvelun näkyvyys
- Maksullisuus
- Voimassaolo
- Tiedostomuoto
Palvelut näkyvät Liityntäkatalogissa, kun ne on lisätty liityntäpalvelimelle.
Jos palvelusi ei näy Liityntäkatalogissa, tarkista, että se on lisätty liityntäpalvelulle sivun Palvelun lisääminen liityntäpalvelimelle ohjeiden mukaisesti.
Jos palvelusi näkyy Liityntäkatalogissa tuntemattomana, katso ohjeet sivulta Palvelun tekninen kuvaus Liityntäkatalogissa.
Tarvittaessa ota yhteyttä Palveluväylän ylläpitoon: palveluvayla@palveluvayla.fi.
Jokaisella palvelulla tulee olla tekninen kuvaus, joka voidaan hakea automaattisesti Palveluväylältä WSDL- tai OpenAPI-tiedostona. Lisäksi voit ladata Liityntäkatalogiin muita liitteitä, kuten PDF-tiedostoja, joissa voit kuvailla tarkemmin esimerkiksi palvelun käyttöehdot.
Dokumentoi REST-arkkitehtuurin mukaiset palvelusi OpenAPI-spesifikaation mukaisesti. Liityntäkatalogi näyttää OpenAPI-kuvauksista esikatselun, jolloin Liityntäkatalogia selaileva käyttäjä saa nopeasti tietoonsa tärkeimmät tiedot palvelustasi. Jos sisällytät kuvaukseen linkkejä, varmista, että ne toimivat eivätkä ole esimerkiksi sisäisiä linkkejä. Lue lisää OpenAPI-dokumentaatiosta:
- OpenAPI's specification (GitHub, englanniksi)Avautuu uuteen ikkunaan.
- OpenAPI's basic structure (englanniksi)Avautuu uuteen ikkunaan.
Lue lisää palvelun teknisestä kuvauksesta Liityntäkatalogissa.
Jos näistä ohjeista ei ollut apua tilanteeseesi, ota yhteyttä Palveluväylän tukeen: palveluvayla@palveluvayla.fi.