Suomi.fi-palveluväylä – testipalvelut

Suomi.fi palveluväylän eri ympäristöissä (FI-DEV, FI-TEST ja FI) on tarjolla kaksi kaikkien liittyneiden organisaatioiden käytössä olevaa testipalvelua. Palvelujen avulla on mahdollisuus varmistaa oman liityntäpalvelimen asennuksen onnistuminen sekä testata X-Road-tiedonsiirtoprotokollan mukaisten SOAP-sanomien lähettämistä ja vastausten käsittelyä.

Liityntäpalvelimen asiakasrajapinta, jonka kautta palveluväylän kautta käytettävissä olevien palvelujen kutsuminen tapahtuu, on muotoa ”https://{host}/”. Osoitteen ”{host}”-osa tulee korvata oman liityntäpalvelimen host-nimellä. Liityntäpalvelimelle lähetettävien pyyntöjen Content-Type-otsikkotiedon arvon tulee olla ”text/xml” ja HTTP-metodin on oltava POST.

IP-osoitteen käyttö kutsuissa ei ole suositeltavaa, sillä se aiheuttaa varmenteisiin liittyviä ongelmia. Ongelmia ilmenee, mikäli liityntäpalvelin kutsussa käytetty host-nimi ei vastaa liityntäpalvelimen varmenteessa olevaa host-nimeä.

Liityntäpalvelimen osoite: https://{host}/ Method: POST Content-Type: text/xml

Alla kuvattujen esimerkkipalveluiden lähdekoodi on vapaasti saatavilla GitHub:ista.

Testipalveluiden WSDL-kuvaus löytyy täältä.

getRandom

GetRandom palvelu ei sisällä kutsuparametrejä ja se palauttaa vastauksenaan satunnaisen kokonaisluvun väliltä 0-100. Hepoimmin palvelun testaaminen onnistuu Firefoxin RESTClient-liitännäisen (esimerkki) tai Curl-komentoriviohjelman avulla. HUOM! Suojatun HTTPS-yhteyden käyttäminen RESTClient-liitännäisellä edellyttää ensin käyntiä selaimella https://{host}/ -osoitteessa ja liityntäpalvelimen varmenteen lisäämistä selaimeen luotettujen varmenteiden joukkoon.

curl -k -d @getRandom.xml --header "Content-Type: text/xml" -X POST https://{host}/

Curl-komennossa on käytetty k-optiota, joka tarkoittaa, että kutsutun palvelun varmennetta ei verifioida. Lisätietoja.

Palvelun kutsumiseen käytettävän SOAP-sanoma on nähtävillä alla. HUOM! Client-lohkon sisältö on korvattava oman organisaatiotunnuksen alle lisätyn alijärjestelmän tiedoilla. Lisäksi <xRoadInstance> elementtiin on laitettava arvoksi oikea palveluväylän ympäristö (FI-DEV, FI-TEST tai FI) jossa SOAP-sanomaa halutaan testata.

<xrd:client id:objectType="SUBSYSTEM">

    <id:xRoadInstance>FI-DEV</id:xRoadInstance>

    <id:memberClass>XXX</id:memberClass>

    <id:memberCode>XXXXXXXX</id:memberCode>

    <id:subsystemCode>XXXXXXXX</id:subsystemCode>

</xrd:client>

Kysely

<SOAP-ENV:Envelope 
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:id="http://x-road.eu/xsd/identifiers"
    xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">
        <SOAP-ENV:Header>
                <xrd:client id:objectType="SUBSYSTEM">
                        <id:xRoadInstance>FI-DEV</id:xRoadInstance>
                        <id:memberClass>XXX</id:memberClass>
                        <id:memberCode>XXXXXXXX</id:memberCode>
                        <id:subsystemCode>XXXXXXXX</id:subsystemCode>
                </xrd:client>
                <xrd:service id:objectType="SERVICE">
                        <id:xRoadInstance>FI-DEV</id:xRoadInstance>
                        <id:memberClass>GOV</id:memberClass>
                        <id:memberCode>0245437-2</id:memberCode>
                        <id:subsystemCode>TestService</id:subsystemCode>
                        <id:serviceCode>getRandom</id:serviceCode>
                        <id:serviceVersion>v1</id:serviceVersion>
                </xrd:service>
                <xrd:userId>test</xrd:userId>
                <xrd:id>ID11234</xrd:id>
                <xrd:protocolVersion>4.0</xrd:protocolVersion>
        </SOAP-ENV:Header>
        <SOAP-ENV:Body>
                <ns1:getRandom xmlns:ns1="http://test.x-road.fi/producer">
                        <ns1:request />
                </ns1:getRandom>
        </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Esimerkkivastaus

<?xml version="1.0" encoding="utf-8" ?>

<SOAP-ENV:Envelope 
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:id="http://x-road.eu/xsd/identifiers" 
    xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">

    <SOAP-ENV:Header>

        <xrd:client id:objectType="SUBSYSTEM">

            <id:xRoadInstance>FI-DEV</id:xRoadInstance>

            <id:memberClass>XXX</id:memberClass>

            <id:memberCode>XXXXXXXX</id:memberCode>

            <id:subsystemCode>XXXXXXXX</id:subsystemCode>

        </xrd:client>

        <xrd:service id:objectType="SERVICE">

            <id:xRoadInstance>FI-DEV</id:xRoadInstance>

            <id:memberClass>GOV</id:memberClass>

            <id:memberCode>0245437-2</id:memberCode>

            <id:subsystemCode>TestService</id:subsystemCode>

            <id:serviceCode>getRandom</id:serviceCode>

            <id:serviceVersion>v1</id:serviceVersion>

        </xrd:service>

        <xrd:userId>test</xrd:userId>

        <xrd:id>ID11234</xrd:id>

        <xrd:protocolVersion>4.0</xrd:protocolVersion>

        <xrd:requestHash algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">dauzLQn7kxUy6vnuVV8ygL5wa+Nl21ztO1gIIiAUGZAMHAkW0RF6P5NTf4PoMv6SabTsp/fmKxsjq64ecSoBrw==</xrd:requestHash>

    </SOAP-ENV:Header>

    <SOAP-ENV:Body>

        <ts1:getRandomResponse xmlns:ts1="http://test.x-road.fi/producer">

            <ts1:request/>

            <ts1:response>

                <ts1:data>87</ts1:data>

            </ts1:response>

        </ts1:getRandomResponse>

    </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

helloService

HelloService-palvelu sisältää name-kutsuparametrin ja palauttaa vastauksenaan name-parametrin arvona annetulle nimelle kohdistetun tervehdyksen. Helpoimmin palvelun testaaminen onnistuu Firefoxin RESTClient-liitännäisen (esimerkki) tai Curl-komentoriviohjelman avulla. HUOM! Suojatun HTTPS-yhteyden käyttäminen RESTClient-liitännäisellä edellyttää ensin käyntiä selaimella https://{host}/ -osoitteessa ja liityntäpalvelimen varmenteen lisäämistä selaimeen luotettujen varmenteiden joukkoon.

curl -k -d @helloService.xml --header "Content-Type: text/xml" -X POST https://{host}/

Curl-komennossa on käytetty k-optiota, joka tarkoittaa, että kutsutun palvelun varmennetta ei verifioida. Lisätietoja.

<xrd:client id:objectType="SUBSYSTEM">

    <id:xRoadInstance>FI-DEV</id:xRoadInstance>

    <id:memberClass>XXX</id:memberClass>

    <id:memberCode>XXXXXXXX</id:memberCode>

    <id:subsystemCode>XXXXXXXX</id:subsystemCode>

</xrd:client>

Kysely

<SOAP-ENV:Envelope 
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:id="http://x-road.eu/xsd/identifiers" 
    xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">

    <SOAP-ENV:Header>

        <xrd:client id:objectType="SUBSYSTEM">

            <id:xRoadInstance>FI-DEV</id:xRoadInstance>

            <id:memberClass>XXX</id:memberClass>

            <id:memberCode>XXXXXXXX</id:memberCode>

            <id:subsystemCode>XXXXXXXX</id:subsystemCode>

        </xrd:client>

        <xrd:service id:objectType="SERVICE">

            <id:xRoadInstance>FI-DEV</id:xRoadInstance>

            <id:memberClass>GOV</id:memberClass>

            <id:memberCode>0245437-2</id:memberCode>

            <id:subsystemCode>TestService</id:subsystemCode>

            <id:serviceCode>helloService</id:serviceCode>

            <id:serviceVersion>v1</id:serviceVersion>

        </xrd:service>

        <xrd:userId>test</xrd:userId>

        <xrd:id>ID11234</xrd:id>

        <xrd:protocolVersion>4.0</xrd:protocolVersion>

    </SOAP-ENV:Header>

    <SOAP-ENV:Body>

        <ns1:helloService xmlns:ns1="http://test.x-road.fi/producer">

            <ns1:request>

                <ns1:name>Test</ns1:name>

            </ns1:request>

        </ns1:helloService>

    </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Esimerkkivastaus

<?xml version="1.0" encoding="utf-8" ?>

<SOAP-ENV:Envelope 
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:id="http://x-road.eu/xsd/identifiers" 
    xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">

    <SOAP-ENV:Header>

        <xrd:client id:objectType="SUBSYSTEM">

            <id:xRoadInstance>FI-DEV</id:xRoadInstance>

            <id:memberClass>XXX</id:memberClass>

            <id:memberCode>XXXXXXXX</id:memberCode>

            <id:subsystemCode>XXXXXXXX</id:subsystemCode>

        </xrd:client>

        <xrd:service id:objectType="SERVICE">

            <id:xRoadInstance>FI-DEV</id:xRoadInstance>

            <id:memberClass>GOV</id:memberClass>

            <id:memberCode>0245437-2</id:memberCode>

            <id:subsystemCode>TestService</id:subsystemCode>

            <id:serviceCode>helloService</id:serviceCode>

            <id:serviceVersion>v1</id:serviceVersion>

        </xrd:service>

        <xrd:userId>test</xrd:userId>

        <xrd:id>ID11234</xrd:id>

        <xrd:protocolVersion>4.0</xrd:protocolVersion>

        <xrd:requestHash algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">DdcMY5JkPhUbnT+sBjwZdFtTfPlHHEAuUr+Rl1eIVkqHiGnR/82aYErj+p7cRE9IusYrvQ2TyVtrSjNgbVQ2FQ==</xrd:requestHash>

    </SOAP-ENV:Header>

    <SOAP-ENV:Body>

        <ts1:helloServiceResponse xmlns:ts1="http://test.x-road.fi/producer">

            <ts1:request>

                <ts1:name>Test</ts1:name>

            </ts1:request>

            <ts1:response>

                <ts1:message>Hello Test! Greetings from adapter server!</ts1:message>

            </ts1:response>

        </ts1:helloServiceResponse>

    </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Versionro	Mitä tehty	Pvm/henkilö
1.0	Dokumentti julkaistu (siirretty palveluvayla.fi osoitteesta eSuomi.fi sivuille).	27.09.17 / HH
1.1	Linkit päivitetty oikeisiin osoitteisiin.	24.11.17 / HH