Palvelun tekninen kuvaus Liityntäkatalogissa

Jokaisella palvelulla tulee yleistajuisen kuvauksen lisäksi olla tekninen kuvaus, joka haetaan automaattisesti Liityntäkatalogiin Palveluväylältä WSDL- tai OpenAPI-tiedostona. Tekniselle kuvaukselle voi antaa myös sanallisen kuvauksen liitetiedostojen lisäksi.  Organisaation tulee lisätä kuvaus liityntäpalvelimen hallintakäyttöliittymässä ja tämän jälkeen se julkaistaan automaattisesti Liityntäkatalogissa.

Dokumentoi REST-arkkitehtuurin mukaiset palvelusi OpenAPI-spesifikaation mukaisesti. Liityntäkatalogi näyttää OpenAPI-kuvauksista esikatselun, jolloin Liityntäkatalogia selaileva 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 specification (GitHub, englanniksi)Avautuu uuteen ikkunaan.
• OpenAPI basic structure (englanniksi)Avautuu uuteen ikkunaan.

Huomioi, että kuvauksen täytyy olla OpenAPI 3.0 -version mukainen, jotta esikatselu näkyy automaattisesti Liityntäkatalogissa. Jos käytät esimerkiksi OpenAPI 2.0 versiota, sinun täytyy lisätä kuvaus manuaalisesti Liityntäkatalogiin.

Palvelut, joilta puuttuu WSDL- tai OpenAPI3-kuvaus näkyvät Liityntäkatalogissa tuntemattomina palveluina. Lue lisää tuntemattomista palveluista alta.

Miksi palveluni näkyy tuntemattomana Liityntäkatalogissa?

Palvelusi näkyy tuntemattomana, jos siltä puuttuu rajapintakuvaus liityntäpalvelimen hallintakäyttöliittymästä Palveluväylässä. Ilman rajapintakuvausta Liityntäkatalogi ei voi tunnistaa, onko palvelusi REST- vai SOAP-muotoinen.

Yleensä tuntematon palvelu on REST-palvelu, joka on lisätty REST API Base Path -muotoisena Palveluväylään. Liityntäkatalogi ei tunnista REST API Base Path -polulla lisättyjä REST-palveluja. REST-palvelulla täytyy olla OpenAPI 3 -muotoinen rajapintakuvaus, jotta Liityntäkatalogi voi tunnistaa sen.

Suosittelemme lisäämään REST-palvelut Palveluväylään käyttämällä OpenAPI 3 Description -polkua liityntäpalvelimen hallintakäyttöliittymässä. Tällöin Liityntäkatalogi tunnistaa palvelun ja näyttää rajapintakuvauksen automaattisesti. Vaikka et voisi julkaista rajapintakuvausta OpenAPI 3 -muodossa, suosittelemme silti lisäämään kuvauksen esimerkiksi liitetiedostona.

Jossain tapauksissa SOAP-palvelulta saattaa kadota WSDL-kuvaus, jolloin se näkyy myös tuntemattomana palveluna.

Kuvauksen lisääminen tuntemattomalle palvelulle

Kuvauksen lisäämistapa riippuu siitä, onko palvelusi REST- vai SOAP-palvelu.

1. REST-palvelu, joka on lisätty REST API Base Path -polulla Palveluväylään

Jos et voi julkaista rajapintakuvausta OpenAPI 3 -muodossa, lisää palvelun rajapintakuvaus Liityntäkatalogissa liitetiedostona alijärjestelmälle. Rajapintakuvaus voi olla esimerkiksi JSON-muotoinen Open API 2 -kuvaus. Voit katsoa esimerkkiä Metsäkeskuksen alijärjestelmän kuvauksista.

1. Lisää liitetiedosto alijärjestelmän sivulta valitsemalla Hallinnoi > Liitteet > Lisää uusi liitetiedosto.
2. Täytä kentät. Nimeä liitetiedosto selkeästi, jotta palvelun hyödyntäjät tietävät, mille palvelulle rajapintakuvaus kuuluu.
3. Valitse lopuksi Lisää.

Lisää myös palvelun omalle sivulle lyhyt, yleisluontoinen kuvaus palvelusta ja maininta erillisestä rajapintakuvaus-liitetiedostosta. Lisää kuvaus kyseisen palvelun sivulta valitsemalla Hallinnoi. Tällöin palvelusi näkyy edelleen tuntemattomana, mutta käyttäjät, jotka haluavat hyödyntää palveluasi, voivat ymmärtävät palvelusi toimintaa paremmin rajapintakuvauksen avulla.

Voit muuttaa REST API Base Path -polulla lisätyt palvelut myöhemmin OpenAPI 3 Description -muotoisiksi. Lisää tällöin palvelu OpenAPI 3 kuvauspolulla ensin erikseen ja testaa sen toiminta ennen kuin poistat alkuperäisen REST API Base Path -polun.

2. SOAP-palvelu

SOAP-palvelulla täytyy olla WSDL-kuvaus lisättynä liityntäpalvelimen hallintakäyttöliittymässä, jotta Liityntäkatalogi voi näyttää palvelun rajapintakuvauksen.

Jos SOAP-palvelusi näkyy Liityntäkatalogissa tuntemattomana, tarkista liityntäpalvelimen hallintakäyttöliittymästä, onko WSDL-kuvaus kadonnut. Jos kuvaus on kadonnut, lisää WSDL-kuvaus uudelleen. Kuvaus lisätään automaattisesti myös Liityntäkatalogiin.

Lue ohjeista, miten lisäät WSDL-kuvauksen liityntäpalvelimelle.

Katso myös, millainen WSDL-kuvauksen pitää olla.

Palvelusi pitäisi näkyä normaalisti Liityntäkatalogissa jo seuraavana päivänä.

Jos näistä ohjeista ei ollut apua tilanteeseesi ja tarvitset lisää tukea, ota yhteyttä Liityntäkatalogin tukeen: palveluvayla@palveluvayla.fiAvautuu uuteen ikkunaan..